Dotnet Test Util

Assertions & Attributes

Mon, 01 Jan 0001 00:00:00 +0000

This page covers CustomAssert and the environment-aware test attributes.

CustomAssert

CustomAssert is a static class with the null/empty assertions that come up most often, so you don’t have to spell out Assert.True(collection is null || !collection.Any()) every time. Each method throws the same exception type as a failing Assert, so failures read exactly like normal xUnit failures.

Method	Passes when
`NullOrEmpty(IEnumerable?)`	The collection is `null` or has no elements
`NotNullOrEmpty(IEnumerable?)`	The collection is not `null` and has at least one element
`NullOrEmpty(string?)`	The string is `null` or empty
`NotNullOrEmpty(string?)`	The string is not `null` and not empty
`NullOrWhiteSpace(string?)`	The string is `null`, empty, or only white space
`NotNullOrWhiteSpace(string?)`	The string has at least one non-white-space character

CustomAssert.NullOrEmpty(Array.Empty<int>()); // passes
CustomAssert.NullOrEmpty((IEnumerable?)null); // passes
CustomAssert.NotNullOrEmpty(new[] { 1, 2, 3 }); // passes

CustomAssert.NullOrWhiteSpace(" "); // passes
CustomAssert.NotNullOrWhiteSpace("value"); // passes

The collection overloads treat null and empty the same way, so a null reference never trips up a NullOrEmpty check.

Environment-aware attributes

Four attributes wrap xUnit’s [Fact] and [Theory] so a test can be skipped based on the active environment or an explicit condition:

Attribute	Wraps	Intended use
`UnitFactAttribute`	`[Fact]`	Unit test
`UnitTheoryAttribute`	`[Theory]`	Data-driven unit test
`FunctionalFactAttribute`	`[Fact]`	Functional / integration test
`FunctionalTheoryAttribute`	`[Theory]`	Data-driven functional test

All four share the same two optional parameters:

UnitFact(EnvironmentType[]? environments = null, bool skipCondition = false)

environments — the environments in which the test must not run. The current environment is read from the ASPNETCORE_ENVIRONMENT variable and compared case-insensitively. When it matches one of the listed environments, the test is skipped with the reason Test can't run on {environment}. null (the default) imposes no environment restriction.
skipCondition — when true, the test is skipped regardless of the environment, with the reason Condition to skip matched.

// Runs everywhere except Production.
[UnitFact([EnvironmentType.Production])]
public void Calculates_totals() { /* ... */ }

// Never runs while the feature flag is off, on any environment.
[FunctionalFact(skipCondition: FeatureFlags.PaymentsDisabled)]
public void Charges_card() { /* ... */ }

// Data-driven test blocked on Staging and Production.
[UnitTheory([EnvironmentType.Staging, EnvironmentType.Production])]
[InlineData(1)]
[InlineData(2)]
public void Validates_input(int value) { /* ... */ }

EnvironmentType comes from ArturRios.Configuration.Enums and defines Local, Development, Staging and Production.

How the skip decision is made

If skipCondition is true, the test is skipped.
Otherwise, if environments is null or empty, the test runs.
Otherwise, the test is skipped when the current ASPNETCORE_ENVIRONMENT matches one of the listed environments.

Fakes

Mon, 01 Jan 0001 00:00:00 +0000

This page covers the in-memory test doubles: FakeRepository<T> and FakeScheduler.

FakeRepository<T>

FakeRepository<T> is an in-memory implementation of ICrudRepository<T> and IRangeRepository<T> (from ArturRios.Data). It stores entities in a backing list so you can exercise services that depend on a repository without touching a database. T must derive from ArturRios.Data.Entity.

Method	Behavior
`Create(T)`	Assigns a fresh identifier (starting at `1`), stores the entity, returns the id
`GetById(int)`	Returns the matching entity, or `null`
`GetAll()`	Returns every stored entity as `IQueryable<T>`
`Update(T)`	Copies writable properties (except `Id`) onto the stored entity; throws `KeyNotFoundException` when the id is unknown
`Delete(T)`	Removes the entity with the matching id; throws `KeyNotFoundException` when unknown
`UpdateRange(List<T>)`	Updates every entity that exists, silently skipping unknown ids; returns the updated entities
`DeleteRange(List<int>)`	Removes every entity whose id is listed; returns the ids that were actually removed

public class Person : Entity
{
 public string Name { get; set; } = string.Empty;
 public int Age { get; set; }
}

var repository = new FakeRepository<Person>();

var annId = repository.Create(new Person { Name = "Ann", Age = 30 }); // annId == 1
var bobId = repository.Create(new Person { Name = "Bob", Age = 25 }); // bobId == 2

repository.Update(new Person { Id = annId, Name = "Ann Smith", Age = 31 });

var ann = repository.GetById(annId); // Name == "Ann Smith"
var all = repository.GetAll().ToList(); // two people

repository.DeleteRange([annId, bobId]);

Update uses reflection to copy every writable property from the incoming entity onto the stored one, so it mirrors the behavior of a real ORM update where the identifier is preserved.

FakeScheduler

FakeScheduler simulates a scheduled (delayed) dispatch of a command or query through an ArturRios.Mediator.CommandQueryMediator. It waits for a configurable delay and then dispatches, which is useful for testing code paths that would otherwise run on a timer or background schedule.

FakeScheduler(CommandQueryMediator mediator, int waitTimeInSeconds = 60)

Method	Behavior
`CreateCommandSchedule<TCommand, TCommandOutput>(TCommand)`	Waits, then dispatches the command
`CreateQuerySchedule<TQuery, TQueryOutput>(TQuery)`	Waits, then dispatches the query

Pass a small waitTimeInSeconds (for example 0) to keep tests fast:

var services = new ServiceCollection();
services.AddSingleton<ICommandHandlerAsync<PingCommand, PingCommandOutput>>(handler);
var provider = services.BuildServiceProvider();

var mediator = new CommandQueryMediator(provider.GetRequiredService<IServiceScopeFactory>());
var scheduler = new FakeScheduler(mediator, waitTimeInSeconds: 0);

await scheduler.CreateCommandSchedule<PingCommand, PingCommandOutput>(new PingCommand { Value = "ping" });
// the handler has now been invoked through the mediator

Web API Testing

Mon, 01 Jan 0001 00:00:00 +0000

WebApiTest<T> is a base class for functional web API tests. It hosts your API in memory with WebApplicationFactory<T> and exposes an HttpGateway plus helpers for authenticating and authorizing requests.

Getting started

Derive from WebApiTest<T>, where T is the entry point of the API under test (typically its Program class), and pass the environment to run as:

public class ProductsApiTests : WebApiTest<Program>
{
 private static readonly Credentials Credentials = new("user@test.com", "secret123");

 public ProductsApiTests() : base(EnvironmentType.Local) { }

 [Fact]
 public async Task Rejects_anonymous_requests()
 {
 var response = await Gateway.GetAsync<DataOutput<ProductOutput>>("/products/1");

 Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
 }

 [Fact]
 public async Task Creates_a_product()
 {
 await AuthenticateAndAuthorizeAsync(Credentials, "/auth");

 var response = await Gateway.PostAsync<DataOutput<ProductOutput>>("/products", new { Name = "Widget" });

 Assert.Equal(HttpStatusCode.OK, response.StatusCode);
 }
}

The constructor sets ASPNETCORE_ENVIRONMENT to the given environment (lower-cased), starts the in-memory host, and creates the gateway against it.

Members

Member	Purpose
`Gateway`	The `HttpGateway` bound to the in-memory host; use it for all requests
`AuthenticateAsync(Credentials, authRoute)`	Posts credentials, returns the `Authentication` payload, throws `TestException` on failure
`Authorize(authToken)`	Adds a `Bearer` token to the gateway’s default request headers
`AuthenticateAndAuthorizeAsync(Credentials, authRoute)`	Authenticates and applies the returned token in one call

Credentials and Authentication come from ArturRios.Util.WebApi.Security.Records. The gateway helpers (GetAsync<T>, PostAsync<T>, PutAsync<T>, PatchAsync<T>, DeleteAsync<T>) return HttpOutput<T> with StatusCode, Headers and a deserialized Body.

Authentication contract

AuthenticateAsync expects the authentication route to return a DataOutput<Authentication> with HTTP 200 and:

a successful output (no errors),
a non-null Data, and
a non-empty Data.Token.

When any of these is missing it throws TestException("Could not authenticate"). On success, the token is returned (and applied to the gateway headers when you use AuthenticateAndAuthorizeAsync).

Resource cleanup

WebApiTest<T> implements IDisposable and disposes the underlying WebApplicationFactory<T> (and the HTTP clients it created) when the test class is torn down. If you override disposal in a derived class, call the protected Dispose(bool) overload so the host is still released.