Archetypical.Software.Vega.Api.IntegrationTests.Framework 2.7.1

Archetypical.Software.Vega.Api.IntegrationTests.Framework

Reusable integration-testing primitives for applications built on Archetypical.Software.Vega.Api.Abstractions.

This package provides:

• A lightweight in-process Vega API host backed by Microsoft.AspNetCore.TestHost.
• A set of docker-backed database fixtures (via Testcontainers) for common providers.
• Small xUnit helpers for skipping tests when Docker/Testcontainers is unavailable.

Installation

Reference the package from your test project:

<ItemGroup>
  <PackageReference Include="Archetypical.Software.Vega.Api.IntegrationTests.Framework" Version="<version>" />
</ItemGroup>

Vega test host

Minimal usage

The host starts a VegaApiApplication in-memory (TestServer) and returns:

• WebApplication App
• HttpClient Client

using Archetypical.Software.Vega.Api.IntegrationTests.Framework.Hosting;

var (app, client) = await VegaTestHost.StartAsync(
    new Dictionary<string, string?>
    {
        ["VEGA:DBCONTEXT:PROVIDER"] = "INMEMORY"
    },
    options =>
    {
        options.ControllerAssemblies.Add(typeof(MyController).Assembly);
    });

await using (app)
{
    var resp = await client.GetAsync("/healthz");
    resp.EnsureSuccessStatusCode();
}

Fluent builder

For more complex setups you can use a fluent builder:

using Archetypical.Software.Vega.Api.IntegrationTests.Framework.Hosting;

var (app, client) = await VegaTestHost.CreateBuilder()
    .WithServiceName("MyService-IntegrationTests")
    .AddConfiguration("VEGA:DBCONTEXT:PROVIDER", "SQLITE")
    .AddConfiguration("VEGA:DBCONTEXT:CONNECTIONSTRING", "Data Source=:memory:")
    .AddControllerAssembly(typeof(MyController).Assembly)
    .WithEnsureCreated<MyDbContext>()
    .StartAsync();

await using (app)
{
    var resp = await client.GetAsync("/healthz");
    resp.EnsureSuccessStatusCode();
}

Initialization hooks

If you need custom initialization (seeding data, schema, etc.), provide InitializeAsync:

options.InitializeAsync = async sp =>
{
    using var scope = sp.CreateScope();
    var db = scope.ServiceProvider.GetRequiredService<MyDbContext>();
    await db.Database.EnsureCreatedAsync();
};

You can also reuse the built-in helper:

options.InitializeAsync = VegaTestHost.EnsureCreatedWithRetry<MyDbContext>(attempts: 10, delaySeconds: 2);

Docker-backed database fixtures

All fixtures inherit DockerFixtureBase and expose:

• bool IsAvailable
• string? UnavailableReason

Use SkipIfUnavailable.Docker(fixture) at the start of tests to skip/guard when Docker is not reachable.

Postgres

using Archetypical.Software.Vega.Api.IntegrationTests.Framework.Fixtures;
using Archetypical.Software.Vega.Api.IntegrationTests.Framework.Utilities;

public class PostgresTests : IClassFixture<PostgresFixture>
{
    private readonly PostgresFixture _fixture;

    public PostgresTests(PostgresFixture fixture) => _fixture = fixture;

    [Fact]
    public async Task Works()
    {
        SkipIfUnavailable.Docker(_fixture);

        var (app, client) = await VegaTestHost.StartAsync(
            new Dictionary<string, string?>
            {
                ["VEGA:DBCONTEXT:PROVIDER"] = "POSTGRESQL",
                ["VEGA:DBCONTEXT:CONNECTIONSTRING"] = _fixture.ConnectionString
            },
            options => options.ControllerAssemblies.Add(typeof(MyController).Assembly));

        await using (app)
        {
            // ...
        }
    }
}

Optional configuration via builder:

var fixture = PostgresFixture.CreateBuilder()
    .WithDatabase("vega")
    .WithUsername("postgres")
    .WithPassword("postgres")
    .Build();

CockroachDB

var fixture = CockroachFixture.CreateBuilder()
    .WithDatabase("defaultdb")
    .Build();

SQL Server

var fixture = SqlServerFixture.CreateBuilder()
    .WithPassword("yourStrong(!)Password")
    .Build();

ClickHouse

var fixture = ClickhouseFixture.CreateBuilder()
    .WithDatabase("default")
    .WithReadyTimeoutSeconds(300)
    .Build();

Notes

• This package targets net9.0 and net10.0.
• Docker-based tests should be written defensively; use SkipIfUnavailable.Docker(...) to avoid false negatives on CI/dev machines without Docker.
• dotnet test should be run against your test projects/solution; this package itself is not a test project.