Resrcify.SharedKernel.IntegrationTesting 4.4.0

Resrcify.SharedKernel.IntegrationTesting

Resrcify.SharedKernel.IntegrationTesting holds the integration-test fixtures the services share: PostgreSQL and RabbitMQ in Testcontainers, and a host fixture that runs a service's Program in-process on them.

Table of Contents

• What you get
• Prerequisites
• Install
• Hosting a service: ServiceHostFixture<TProgram>
  • Settings
  • A shared network
  • Starting more: StartDependenciesAsync
  • Getting the started host ready: OnHostStartedAsync
  • A service without a database
  • What a service changes
  • A Program with its own configuration builder
  • What the service logged: Logs
  • The message bus on the test harness: UsesMessageBusTestHarness
• Container fixtures
  • A production-like broker
  • Events on a real broker: PublishedEventListener

What you get

• ServiceHostFixture<TProgram> (Factories/): a WebApplicationFactory<TProgram> and xUnit fixture that starts PostgreSQL (unless the service has none), RabbitMQ when asked and whatever else the service starts in StartDependenciesAsync, hands the host the conventional settings through its configuration, starts the host and lets the service get it ready in OnHostStartedAsync (pause its jobs, seed data).
• IntegrationFactoryBase<TProgram> (Factories/): a WebApplicationFactory whose subclass supplies settings, for hosts that own no containers. The settings win over appsettings*.json and environment variables, with WebApplication.CreateBuilder and Host.CreateDefaultBuilder alike.
• ServiceHostFixture.Logs: what the host logged, through the logging abstraction and Serilog, in Microsoft's FakeLogCollector; UsesMessageBusTestHarness: the service's buses on the message bus test harness, in memory.
• PostgresContainerFixture, RabbitMqContainerFixture (Fixtures/): one container each, on the images production runs, postgres:18 and rabbitmq:4.3.4-management (the RabbitMQ Cluster Operator v2.23.0's default) (RESRCIFY_TEST_POSTGRES_IMAGE / RESRCIFY_TEST_RABBITMQ_IMAGE replace the image for every fixture), their database and credentials set with init properties (no subclass), a readiness probe, JoinNetwork(network, aliases), and for RabbitMQ production's queue defaults (ProductionQueueDefaults), QueuesAsync, AddQuorumVirtualHostAsync, Connection and WaitForExchangePublish.
• With Resrcify.SharedKernel.MessageBus.Testing (which this references): PublishedEventListener, a subscriber to the integration events a service publishes on a real broker.

Prerequisites

• .NET 10 SDK and Docker on the machine running the tests.

Install

<PackageReference Include="Resrcify.SharedKernel.IntegrationTesting" Version="<latest>" />

<PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" />

Hosting a service: ServiceHostFixture<TProgram>

public sealed class ShardHostFixture
    : ServiceHostFixture<Program>
{
    // The service's database and credentials; production's image. null: no database.
    protected override PostgresContainerFixture CreatePostgres()
        => new() { Database = "ShardDb", Username = "ShardUser", Password = "K33pTr4ck" };
    // null (the default): no broker. Production's quorum queues and delivery limit.
    protected override RabbitMqContainerFixture? CreateRabbitMq()
        => new() { ProductionQueueDefaults = true };
    protected override bool UsesNetwork => true;                                               // see below

    protected override void ConfigureSettings(IDictionary<string, string?> settings)
        => settings["Patreon:Token"] = "test";

    protected override void ConfigureTestServices(IServiceCollection services)
        => services.Replace(ServiceDescriptor.Singleton<IClock>(new FixedClock()));
}

[CollectionDefinition(Name)]
public sealed class ShardIntegrationCollection
    : ICollectionFixture<ShardHostFixture>
{
    public const string Name = nameof(ShardIntegrationCollection);
}

When it starts (InitializeAsync) it starts the containers (at once), adds the conventional settings, runs StartDependenciesAsync, then ConfigureSettings, then builds and starts the host (a plain WebApplicationFactory would wait for the first CreateClient() or Services), then runs OnHostStartedAsync. Postgres, RabbitMq, Network and Settings are there for the tests. Disposing it stops the host, then what was handed to DisposeWithFixture (last first), then the containers, then deletes the network. A start that fails (a container, StartDependenciesAsync, ConfigureSettings, the host's own start, OnHostStartedAsync) tears down what it had started the same way before it throws, so nothing is left running, and the failure is the fixture's, not the first test's.

Settings

ConfigureSettings adds to them or changes them; the environment is Development (override Environment). They reach the host with UseSetting, so Program sees them in builder.Configuration while it registers its services (where AddPostgresDbContext binds Database and the services bind MessageBus), and as the last configuration source, so they win over appsettings*.json, environment variables and the Program's own sources on the generic host (Host.CreateDefaultBuilder + Startup) too, where UseSetting alone lost to appsettings.json. They belong to that host alone: nothing is written to the process' environment, so two fixtures in two collections can run at once, each on its own containers. The old fixtures' Environment.SetEnvironmentVariable("Database__Host", ...) were process-wide: they leaked into every other collection and forced all tests into one.

The credentials come from the container's connection string, which Testcontainers doesn't quote: keep ; out of a test database's password.

A shared network

With UsesNetwork, the fixture creates a network and puts PostgreSQL on it as postgres and RabbitMQ as rabbitmq (PostgresNetworkAlias, RabbitMqNetworkAlias). A container a test starts on Network (another service, say) reaches them at postgres:5432 and rabbitmq:5672, while the in-process host keeps using the mapped ports.

Starting more: StartDependenciesAsync

A service that needs another container (SwgohApi's image on the fixture's network, say, whose URL goes into the settings) starts it in StartDependenciesAsync. It runs once PostgreSQL, RabbitMQ and the network are up, with the conventional Settings in place, and before ConfigureSettings and the host:

public sealed class SentinelHostFixture
    : ServiceHostFixture<Program>
{
    private SwgohApiPod _swgohApi = default!;

    protected override PostgresContainerFixture? CreatePostgres() => new PostgresFixture();
    protected override RabbitMqContainerFixture? CreateRabbitMq() => new RabbitMqFixture();
    protected override bool UsesNetwork => true;          // the pod reaches rabbitmq:5672

    protected override async Task StartDependenciesAsync(CancellationToken cancellationToken)
        => _swgohApi = DisposeWithFixture(await SwgohApiPod.StartAsync(RabbitMq!, Network!, cancellationToken));

    protected override void ConfigureSettings(IDictionary<string, string?> settings)
        => settings["SwgohApiService:Url"] = _swgohApi.Url.ToString();
}

DisposeWithFixture(x) has the fixture dispose x when it is torn down: after the host has stopped, before RabbitMQ, PostgreSQL and the network, the last one handed over first. It takes an IAsyncDisposable (a Testcontainers container, returned for chaining) or an IAsyncLifetime (a container fixture of this package), and may be called at any time (a test that starts another pod later hands it over too). Hand a container over before starting it (var c = DisposeWithFixture(builder.Build()); await c.StartAsync(cancellationToken);), so it is removed even if its own start fails. The token is cancelled when the fixture is torn down.

Getting the started host ready: OnHostStartedAsync

OnHostStartedAsync(services, cancellationToken) runs once, at the end of InitializeAsync: after the host has started (its hosted services too, so Quartz's scheduler is running) and before the first test. services is the host's root provider (Services); create a scope for scoped services. Sentinel's system tests pause the scheduled jobs, which the tests then run on demand, and leave the outbox's on its schedule:

public sealed class SentinelSystemHostFixture
    : ServiceHostFixture<Program>
{
    private static readonly string[] ScheduledJobs = ["UpdateGuildsJob", "UpdateTrackedPlayersJob", /* … */];

    protected override async Task OnHostStartedAsync(IServiceProvider services, CancellationToken cancellationToken)
    {
        var scheduler = await services.GetRequiredService<ISchedulerFactory>().GetScheduler(cancellationToken);
        foreach (var job in ScheduledJobs)
            await scheduler.PauseJob(new JobKey(job), cancellationToken);
        // or every job, the outbox's included: await scheduler.PauseAll(cancellationToken);

        await using var scope = services.CreateAsyncScope();
        await SeedAsync(scope.ServiceProvider, cancellationToken);   // data every test reads
    }
}

A failure in it tears down the host and everything started before it, like any failed start; it doesn't run when the start failed earlier (the host's own start included). A job whose trigger fires as the scheduler starts may run once before the hook pauses it: give such a job a start delay if a test can't tolerate that run.

There is no built-in "pause Quartz" switch: this package doesn't depend on Quartz (a service without jobs shouldn't ship it), and which jobs to hold differs per service (Sentinel keeps the outbox running). The hook is the three lines above.

A service without a database

CreatePostgres() returning null starts no PostgreSQL and gives no Database:* or Migrations:Run settings (Discord's bot has no database); reading Postgres then throws InvalidOperationException.

protected override PostgresContainerFixture? CreatePostgres() => null;

What a service changes

Before (~55 lines per service):

public sealed class ShardHostFixture : WebApplicationFactory<Program>, IAsyncLifetime
{
    public PostgresFixture Postgres { get; } = new();
    public RabbitMqFixture RabbitMq { get; } = new();

    public async Task InitializeAsync()
    {
        await Postgres.InitializeAsync();
        await RabbitMq.InitializeAsync();
        Environment.SetEnvironmentVariable("Database__Host", Postgres.Host);
        // ... nine more
    }

    async Task IAsyncLifetime.DisposeAsync() { ... }

    protected override void ConfigureWebHost(IWebHostBuilder builder) => builder.UseEnvironment("Development");
}

After: the class above. The service's PostgresFixture / RabbitMqFixture subclasses, which only set credentials (and an image), go: their values move into CreatePostgres() / CreateRabbitMq() as init properties (Database, Username, Password), and the image stays production's. A RabbitMqFixture that built its own network can drop it for UsesNetwork (its alias is the same, rabbitmq). Tests reach the containers as host.Postgres / host.RabbitMq, the broker as the bus connects to it as host.RabbitMq.Connection, and its user as host.RabbitMq.BrokerUsername / BrokerPassword.

What the service logged: Logs

Logs is Microsoft's FakeLogCollector (Microsoft.Extensions.Diagnostics.Testing): every line the host logged that its own level filters let through, with its category, level, message, exception and structured state.

await client.PostAsJsonAsync("/shards", request);
var warning = host.Logs.GetSnapshot().ShouldHaveSingleItem(record => record.Level == LogLevel.Warning);

It hears both ways a service logs: through a provider of the logging abstraction, and, for a service on Serilog, through a sink registered in the container, which AddServiceTelemetry's Serilog reads (ReadFrom.Services). A line arrives once (Serilog bypasses the abstraction's providers). A service setting up Serilog itself without ReadFrom.Services(provider) is heard through the providers only, i.e. not at all. Logs.Clear() between tests in a shared fixture.

The message bus on the test harness: UsesMessageBusTestHarness

public sealed class HarnessShardHostFixture : ServiceHostFixture<Program>
{
    protected override bool UsesMessageBusTestHarness => true;   // no broker: CreateRabbitMq stays null

    protected override PostgresContainerFixture CreatePostgres()
        => new() { Database = "ShardDb", Username = "ShardUser", Password = "K33pTr4ck" };
}

// In a test:
await host.Harness.Published.WaitForAsync<ShardCreated>(e => e.Name == "Main");
await using var players = await host.BusNetwork.StartResponderAsync<GetPlayer, PlayerProfile>(...);

The fixture calls AddMessageBusTestHarness(BusNetwork) after the service's registrations, so every bus of the service runs in memory on BusNetwork, whatever transport it configured (no MessageBus:* settings are needed), recorded by Harness (the service's MessageBusTestHarness; reading it without the switch throws). It replaces the BusNetwork property and the ConfigureTestServices(services => services.AddMessageBusTestHarness(BusNetwork)) each service's Harness*HostFixture wrote.

A Program with its own configuration builder

A Program that reads a configuration it builds itself never sees the fixture's settings:

var configuration = new ConfigurationBuilder()      // Tournament's Program.cs
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();
builder.Services.AddPersistenceServices(configuration);

builder.Configuration already has the same JSON files, environment variables and command line: pass it instead (AddPersistenceServices(builder.Configuration)) before moving such a service to this fixture.

Container fixtures

Use them on their own (IClassFixture<PostgresContainerFixture>) when a test needs a database but no host; CreateIsolatedConnectionString() gives each test class a database of its own. Set the database and credentials with init properties (new PostgresContainerFixture { Database = "ShardDb", Username = "ShardUser", Password = "..." }, new RabbitMqContainerFixture { Username = "messageUser", Password = "..." }), or in a subclass' constructor when xUnit needs a type of its own (public ShardPostgres() => Database = "ShardDb";). Both default to the images production runs: leave Image alone (a test on another version proves less), and try another version for a whole run with RESRCIFY_TEST_POSTGRES_IMAGE / RESRCIFY_TEST_RABBITMQ_IMAGE. Configure (a subclass) still sets any other builder option.

A production-like broker

Production's RabbitMQ declares a queue without a type as a quorum queue and gives every queue a delivery limit of a million (RabbitMQ 4 limits a quorum queue to 20 redeliveries otherwise): Resrcify.Kubernetes' additionalConfig.

new RabbitMqContainerFixture { ProductionQueueDefaults = true }      // the whole broker, as production

var quorum = await rabbitMq.AddQuorumVirtualHostAsync();             // or one virtual host of a shared broker
await host.StartAsync(quorum);                                       // a RabbitMqConnection in that virtual host

var queues = await rabbitMq.QueuesAsync(quorum.VirtualHost);         // name, type (classic, quorum), exclusive
queues.ShouldContain(new RabbitMqQueue("shardmanagement", "quorum", Exclusive: false));

ProductionQueueConfig is the configuration it mounts (/etc/rabbitmq/conf.d/90-production-queues.conf).

Events on a real broker: PublishedEventListener

PublishedEventListener (Resrcify.SharedKernel.MessageBus.Testing) subscribes to a service's integration events on a real broker as another service would: a bus of its own with an input queue of its own, bound to each event's topic (its wire name), recording what arrives.

await using var events = await PublishedEventListener.StartAsync(
    host.RabbitMq!.Connection,
    listen => listen.Listen<ShardCreated>().Listen<ShardRenamed>("ShardRenamedV2"));   // a wire name of its own
await client.PostAsJsonAsync("/shards", request);
var created = await events.Received.WaitForAsync<ShardCreated>(e => e.Name == "Main");

Start it before the publish (a publish before its queue is bound has nowhere to go); disposing it unsubscribes and stops it. It replaces Shard's TopicListener (raw RabbitMQ on RebusTopics) and Sentinel's EventSubscriber.