| Clean Architecture Toolkit for .NET | |||||
|
Clean Architecture Toolkit is a clean, modular architecture foundation for .NET applications. It embraces SOLID principles and focuses on maintainability, testability, and scalability through clear boundaries and pluggable design. |
|
||||
|
| HOME | REPO OVERVIEW | DEMO | |
|||||
Cat.UnitTesting gives you test doubles for the unit tests of your core service. The core service has no technology in it, so its tests need no database. They replace the processors with fakes that record what they got and answer what the test says.
The module is a toolbox of small projects, one per CAT module. You reference only the fakes of the modules you use, so a test project does not pull in fakes for things it never tests.
A fake is dumb on purpose. It returns what the test sets up. It fills no ids and sets no timestamps.
| Package | Role | Install | Downloads |
|---|---|---|---|
| Cat.UnitTesting.Commands | Fake command processor | dotnet add package gmarginet.Cat.UnitTesting.Commands |
|
| Cat.UnitTesting.EventAggregators | Recording subscriber and fake event aggregator | dotnet add package gmarginet.Cat.UnitTesting.EventAggregators |
|
| Cat.UnitTesting.Messaging | Fake message sender | dotnet add package gmarginet.Cat.UnitTesting.Messaging |
|
| Cat.UnitTesting.NUnit | NUnit base class and decorator recorder | dotnet add package gmarginet.Cat.UnitTesting.NUnit |
|
| Cat.UnitTesting.Queries | Fake query processor | dotnet add package gmarginet.Cat.UnitTesting.Queries |
|
| Cat.UnitTesting.Responses.NUnit | NUnit constraints for responses | dotnet add package gmarginet.Cat.UnitTesting.Responses.NUnit |
|
| Cat.UnitTesting.ServiceRequests | Fake service request processor | dotnet add package gmarginet.Cat.UnitTesting.ServiceRequests |
|
| Cat.UnitTesting.Users | Fake user and user accessor | dotnet add package gmarginet.Cat.UnitTesting.Users |
| Namespace | What it holds |
|---|---|
| Cat.UnitTesting.Commands | A command processor for unit tests. It records the commands and returns the responses that the test sets up. |
| Cat.UnitTesting.EventAggregators | Test doubles for the event aggregator: a subscriber that records the events it gets, and an aggregator that records what is published. |
| Cat.UnitTesting.Messaging | A message sender for unit tests. It records the messages that were published or sent, and when they were scheduled. |
| Cat.UnitTesting.NUnit | Helpers for NUnit tests: a base class that builds a service provider, and a recorder for decorator calls. |
| Cat.UnitTesting.Queries | A query processor for unit tests. It records the queries and returns the responses that the test sets up. |
| Cat.UnitTesting.Responses.NUnit | NUnit constraints for responses, such as succeeded, failed, the response type and an error code. |
| Cat.UnitTesting.ServiceRequests | A service request processor for unit tests. It records the service requests and returns the responses that the test sets up. |
| Cat.UnitTesting.Users | A user and a user accessor for unit tests. The test sets the id, the name, the login state and the roles. |
| Module | Why Cat.UnitTesting needs it |
|---|---|
| Cat.Commands | Cat.UnitTesting.Commands fakes ICatCommandProcessor. It references the abstractions only. |
| Cat.Decorators | Cat.UnitTesting.NUnit records the decorators that a module adds. It references the abstractions only. |
| Cat.EventAggregators | Cat.UnitTesting.EventAggregators fakes ICatEventAggregator and implements ICatHandleEvent<T>. It references the abstractions only. |
| Cat.Messaging | Cat.UnitTesting.Messaging fakes ICatMessageSender. It references the abstractions only. |
| Cat.Users | Cat.UnitTesting.Users implements ICatUser and ICatUserAccessor. It references the abstractions only. |
| Cat.ServiceRequests | Cat.UnitTesting.ServiceRequests fakes ICatServiceRequestProcessor. It references the abstractions only. |
| Cat.Queries | Cat.UnitTesting.Queries fakes ICatQueryProcessor. It references the abstractions only. |
| Cat.Responses | The fakes answer with ICatResponse, and the command fake starts with CatResponse.Ok(). |
Give the class under test a FakeCommandProcessor instead of the real ICatCommandProcessor. It records every command in Commands, in order, and Of<T>() gives the ones of one type.
A command without a result gets DefaultResponse, which starts as CatResponse.Ok(). Change it, or set a response per command type with Respond:
using Cat.UnitTesting.Commands;
var commands = new FakeCommandProcessor()
.Respond<TodoDeleteCommand>(CatResponse.NotFound());
var service = new TodoService(commands);
await service.DeleteAsync(7);
Assert.That(commands.Of<TodoDeleteCommand>().Single().TodoId, Is.EqualTo(7));Respond also takes a function. The function gets the command, so the response can depend on it. It can change the command too, as a real handler would, for instance to set an id:
commands.Respond<CustomerCreateOrUpdateCommand>(command =>
{
command.CustomerId = customerId;
return CatResponse.Ok();
});A command with a result has no default, because a fake cannot guess the data. Set it up with both type arguments. A command without a set up response throws a NotSupportedException that names the command. The command is still recorded.
commands.Respond<TodoCreateCommand, int>(CatResponse.Ok(42));
commands.Respond<TodoCreateCommand, int>(command => CatResponse.Ok(command.Title.Length));FakeQueryProcessor works the same way, with two differences. Every query has a result, so Respond always takes both type arguments. And there is no default response, so a query without a set up response throws.
using Cat.UnitTesting.Queries;
var queries = new FakeQueryProcessor()
.Respond<TodoGetQuery, Todo>(CatResponse.Ok(todo))
.Respond<TodoGetListQuery, IList<Todo>>(CatResponse.NotFound<IList<Todo>>());FakeServiceRequestProcessor of Cat.UnitTesting.ServiceRequests works like the command fake. It records the requests in Requests, Of<T>() gives the ones of one type, a request without a result gets DefaultResponse, and a request with a result needs a set up response.
using Cat.UnitTesting.ServiceRequests;
var requests = new FakeServiceRequestProcessor()
.Respond<CleanUpRequest>(CatResponse.InternalServerError())
.Respond<OrderGetRequest, Order>(request => CatResponse.Ok(order));RecordingSubscriber<TEvent> of Cat.UnitTesting.EventAggregators collects the events it gets in Events. Subscribe it to the aggregator of the test. The type can be an interface or a base type, to collect several event types. Keep a reference to the subscriber, because the aggregator holds a subscriber weakly.
using Cat.UnitTesting.EventAggregators;
var events = new RecordingSubscriber<IOrderEvent>();
aggregator.Subscribe(events);
await service.PlaceAsync(order);
Assert.That(events.Events.Single(), Is.TypeOf<OrderConfirmedEvent>());To test code that only publishes, give it a FakeEventAggregator. It records Published and Subscribers, Of<T>() gives the events of one type, and it calls no subscriber. HasSubscribersForEvent answers from the subscribers that the test added.
FakeMessageSender of Cat.UnitTesting.Messaging takes the place of ICatMessageSender. It records every published event and every sent command in Sent, in order, with the time the caller asked to send it at. Of<T>() filters by message class, or by ICatEventMessage or ICatCommandMessage. It sends nothing.
using Cat.UnitTesting.Messaging;
var sender = new FakeMessageSender();
await handler.HandleAsync(request);
Assert.That(sender.Of<OrderPlaced>().Single().OrderId, Is.EqualTo(orderId));
Assert.That(sender.Sent.Single().ScheduledAt, Is.Null);CatIs of Cat.UnitTesting.Responses.NUnit has NUnit constraints for an ICatResponse, typed or not. A failure shows as a normal NUnit failure and prints the response, for example Failed NotFound [DEM-ORD-1004].
using Cat.Responses.Abstractions;
using Cat.UnitTesting.Responses.NUnit;
Assert.That(response, CatIs.Succeeded);
Assert.That(response, CatIs.SucceededWith(CatResponseType.Created));
Assert.That(response, CatIs.Failed);
Assert.That(response, CatIs.FailedWith(CatResponseType.NotFound));
Assert.That(response, CatIs.FailedWithCode("DEM-ORD-1004"));
Assert.That(response, CatIs.FailedWith(CatResponseType.NotFound, "DEM-ORD-1004"));FailedWithCode accepts the code anywhere in the list of errors. The constraints work with ! and &, like other NUnit constraints. The package targets the latest stable .NET, because NUnit 5 has no netstandard2.0 build.
FakeUser of Cat.UnitTesting.Users is an ICatUser that the test can change. It starts as a logged in user without roles. Set UserId, Name and IsAuthenticated, and give it roles with InRole or by changing Roles. When the user never changes during the test, CatUser of Cat.Users.Abstractions is enough.
using Cat.UnitTesting.Users;
var user = new FakeUser { UserId = "alice", Name = "Alice" }.InRole("admin");
var accessor = new FakeUserAccessor { User = user };FakeUserAccessor is an ICatUserAccessor. It starts with CatUser.Anonymous, like a request without a login. To add properties of your own application, such as an email address, derive from FakeUser.
Reset() clears the recorded commands, queries, requests, events or messages and the set up responses. The command and service request fakes also get their original default response back. A new fake per test is simpler, so use Reset() only when a fake lives across tests.
UnitTestBase of Cat.UnitTesting.NUnit suits a fixture that tests against a real service provider, such as the registration of a module. It builds the provider once per fixture from ConfigureServices, and disposes it after the last test. The provider is in ServiceProvider.
using Cat.Queries.Abstractions;
using Cat.Queries.Extensions;
using Cat.UnitTesting.NUnit;
using Microsoft.Extensions.DependencyInjection;
[TestFixture]
public class TodoQueryTests : UnitTestBase
{
protected override void ConfigureServices(ServiceCollection services)
{
services.AddCatQueriesModule(typeof(TodoGetQueryHandler));
}
[Test]
public void TheProcessorIsRegistered()
{
using var scope = ServiceProvider.CreateScope();
Assert.That(scope.ServiceProvider.GetService<ICatQueryProcessor>(), Is.Not.Null);
}
}The package targets the latest stable .NET. The fakes of the other projects target netstandard2.0.
A module that adds a decorator calls ICatDecoratorFactoryBuilder. RecordingDecoratorBuilder only records those calls, so a test can check which decorator was added and in which order. CreateServiceProvider() gives a provider that hands the recorder out. Call the AddCat...Decorator extension method of the module on it.
using Cat.Decorators.Abstractions;
using Cat.Queries.Decorators.Logging.Extensions;
using Cat.UnitTesting.NUnit;
var builder = new RecordingDecoratorBuilder();
builder.CreateServiceProvider().AddCatQueriesModuleLoggingDecorator();
Assert.That(builder.Added.Select(added => added.Order), Is.EqualTo(new[] { CatDecoratorOrder.Logging }));The module has no clock of its own. .NET has FakeTimeProvider in the Microsoft.Extensions.TimeProvider.Testing package. Use that one, and give it to the class under test as a TimeProvider. A test that waits on a delay starts the call, checks that it still waits, moves the clock with Advance, and then awaits the result.
- No database. The unit tests of a core service never need one. The fakes replace the processors, so the tests run without a database.
- No integration tests. If CAT gets integration testing, it will be a separate module.
- No fake workflow or validator processors. Run the real ones through a service provider, as
UnitTestBasebuilds it. - No fake of the guesses. A fake returns what the test says. It fills no ids and sets no timestamps. A test that needs those sets them up with
Respond. - Other test frameworks. The fakes in
Cat.UnitTesting.Commands,Queries,ServiceRequests,EventAggregators,MessagingandUsersdo not depend on a test framework. The NUnit parts areCat.UnitTesting.NUnitandCat.UnitTesting.Responses.NUnit. Another framework gets its own project.