Short, self-contained recipes for setting up each piece of a toolkit-based solution for the first time: test projects, the mock server, modules, validated settings, health checks, workers and telemetry. Each fits in one pull request and ends with a “Done when” check. A solution created with the CLI already has most of them in place (Your First Solution walks through it); in a repository you already have, Adopting an Existing Solution puts them in order.

Add an xUnit v3 test project

The toolkit’s test kits (Anarchy.Toolkit.Testing*) and test targets expect xUnit v3 projects running on Microsoft.Testing.Platform (MTP).

  1. Create the project: <OutputType>Exe</OutputType>, a reference to xunit.v3 and to the Testing kit your tests need (Testing, Testing.Web, Testing.Db.Postgres, …). The kits need Moq 4.21 or later and bring AwesomeAssertions.
  2. Use the v3 companion packages when you need them: AutoFixture.Xunit3, Snapshooter.Xunit3.
  3. Write tests as in the Testing convention: derive from TestCaseBase, pass TestContext.Current.CancellationToken to calls that take a token (xUnit1051, an error in Release builds with warnings as errors), and keep MemberData members static.
  4. Select the MTP runner in global.json: { "test": { "runner": "Microsoft.Testing.Platform" } }.
  5. If the CI server needs test results as files, add Microsoft.Testing.Extensions.TrxReport and pass --report-trx.

Done when: make test_unit discovers and runs the project and reports its tests.

Name test projects by kind

The build finds tests by kind: Unit, Integration and EndToEnd. Name a project after its kind (tests/Unit/Unit.csproj) or give it a segment for the kind plus Tests (Shop.Tests.Unit), and keep one project per kind: projects do not run in parallel with each other, while the tests inside one do.

Keep unit tests free of external resources: packing and container publishing run them, and never the other kinds. A different naming scheme is declared, not renamed: "TestKindAliases": ["EndToEnd=Acceptance"] in .fallout/parameters.json, or an override of IsTestProjectOfKind in build/Build.cs (see Anarchy automation builds).

Done when: make test_unit, make test_integration and make test_end_to_end each run exactly the projects of their kind.

Add the mock server

Use it to stand in for HTTP upstreams in integration and end-to-end tests, without Docker.

  1. Add a runnable project whose name ends in MockServer (for example src/MockServer), referencing Anarchy.Toolkit.Web.MockServer, with return await MockServerEntryPoint.RunAsync(args); as its entry point.
  2. Put expectation files (JSON in MockServer’s format) in a folder per upstream, and add IMockServerBuild to the build with "MockServerExpectations": ["src/MockServer/expectations"].
  3. Pin the port your test settings use ("MockServerPort": 6001): an explicit port fails loudly when it is taken.
  4. Point the applications’ development and test settings at it.
  5. In the integration and end-to-end tests, reference Testing.MockServer and call ShouldAllHaveBeenMatched() on the recorded requests in an assembly fixture, so an unmocked call fails the run.

Done when: make test_end_to_end_mocked passes, and removing one expectation on purpose fails it. More: Mock Server.

Write a module

One IDependencyInjectionModule per feature or adapter, in DependencyInjection/Module/Module<Name>.cs. The module receives its options from the composition root instead of reading a section itself:

public sealed class ModuleCarrierClient(Func<IConfiguration, CarrierClientSettings> settings) : IDependencyInjectionModule
{
    public IServiceCollection RegisterServices(IServiceCollection services, IConfiguration configuration, IHostEnvironment environment)
    {
        var options = settings(configuration);
        services.AddSingleton(options);
        services.AddHttpClient<ICarrierClient, CarrierClient>(client => client.BaseAddress = options.BaseAddress);
        return services;
    }
}

services.UseModule(new ModuleCarrierClient(c => c.Get<AppSettings>()!.CarrierClient), configuration, environment);

Add a test that registers the module on an empty ServiceCollection and resolves it with ValidateOnBuild. If a plain Add* extension is useful on its own, the module calls it. See Dependency Injection.

Done when: the module test passes and the application resolves the service at startup.

Add validated settings

  1. Add AppSettings : IAppSettings with one property per section, each marked [Required, ValidateObjectMembers] where it must be present.
  2. Add ModuleAppSettings : ModuleAppSettingsBase<AppSettings> and register ModuleLibConfiguration<ModuleAppSettings, AppSettings>, which also registers telemetry and secrets.
  3. List the keys a developer must provide in appsettings.json.template; make appsettings asks for them.
  4. Add a test that boots the settings from each environment’s configuration, and one that removes a section and expects the boot to fail.

ValidateDataAnnotations does not recurse into nested objects: validate them from AppSettings (IValidatableObject).

Done when: the application fails to start when a required section is missing, and starts with the template’s keys filled in.

Add a health check

One class per dependency: derive HealthCheckBase, set Name and implement CheckAsync (return to pass, throw to fail; timing and failures are handled). Register it as an IHealthCheck, or use a provider’s ready-made reports (ModulePostgresHealthReport). Web hosts serve them through the health controller, workers through AddServiceHealthCheckWorker(assembly) at /health/instance, /health/services and /health/status.

Done when: the services endpoint lists the check, and returns HTTP 500 when the dependency is unavailable.

Add a worker

Derive MonitoredWorkerBase and implement RunIterationAsync, returning true when it did work (the next run follows the recurring interval) or false when idle (the delayed interval). The loop, cancellation, failure logging and a health.ping metric come with it. Register the worker with services.AddHostedService<TWorker>() in a module. Work that must finish before the first request (a cache preload) goes in a hosted service’s StartAsync, registered before the web host starts.

Done when: the worker logs and counts each iteration through AppTelemetry, stops cleanly on cancellation, and its metrics appear in your backend.

Register telemetry

ModuleLibConfiguration already registers AppTelemetry. Add your logging providers and, for metrics and traces, an OpenTelemetry OTLP exporter listening to the toolkit meter; package them as a ModuleTelemetryBase when several solutions share the setup. See Observability and Bringing your company stack.

Done when: a log line and a metric written through AppTelemetry reach your backend, with the correlation ID on the log line.