Alba Documentation

Alba uses an extension model via the IAlbaExtension interface to allow users to modify the application under test before it starts or perform actions after it has started.

An extension can implement two primary lifecycle methods:

1. Configure(IAlbaHostBuilder builder): Runs before the application starts. It provides an IAlbaHostBuilder to add or replace services (ConfigureServices) or add configuration sources (ConfigureConfiguration). This works regardless of whether you are using IHostBuilder, WebApplicationBuilder, or WebApplicationFactory.
2. Start(IAlbaHost host): Runs after the application has started and the DI container is available. This is useful for registering setup or teardown actions.

Extensions are passed as an optional array to AlbaHost.For<T>().

// Example of passing an extension to AlbaHost
var securityStub = new AuthenticationStub().With("foo", "bar");
var host = await AlbaHost.For<WebAppSecuredWithJwt.Program>(securityStub);

You can override application configuration, environment settings, or service registrations during the AlbaHost initialization. This is useful for injecting mocks or stubs.

Configuration Overrides

Use the configuration delegate in AlbaHost.For<T> to call UseEnvironment or ConfigureServices.

Lifecycle Hooks

Alba provides BeforeEach and AfterEach hooks to perform data setup or cleanup around every scenario executed by the host.

var stubbedWebService = new StubbedWebService();

await using var host = await AlbaHost.For<global::Program>(x =>
{
    // override the environment
    x.UseEnvironment("Testing");
    
    // override service registrations
    x.ConfigureServices(s =>
    {
        s.AddSingleton<IExternalWebService>(stubbedWebService);
        s.PostConfigure<MvcNewtonsoftJsonOptions>(o =>
            o.SerializerSettings.TypeNameHandling = TypeNameHandling.All);
    });
});

host.BeforeEach(httpContext =>
    {
        // do some data setup or clean up before every single test
    })
    .AfterEach(httpContext =>
    {
        // do any kind of cleanup after each scenario completes
    });

To improve performance in larger test suites, use xUnit's IClassFixture<T> to share a single AlbaHost instance across all tests within a single test class.

1. Create a fixture class implementing IAsyncLifetime to manage the AlbaHost lifecycle.
2. Inject the fixture into your test class via the constructor.

// 1. Define the fixture
public class WebAppFixture : IAsyncLifetime
{
    public IAlbaHost AlbaHost = null!;

    public async ValueTask InitializeAsync()
    {
        AlbaHost = await Alba.AlbaHost.For<WebApp.Program>(builder =>
        {
            // Configure all the things
        });
    }

    public async ValueTask DisposeAsync()
    {
        await AlbaHost.DisposeAsync();
    }
}

// 2. Use the fixture in a test class
public class ContractTestWithAlba : IClassFixture<WebAppFixture>
{
    public ContractTestWithAlba(WebAppFixture app)
    {
        _host = app.AlbaHost;
    }

    private readonly IAlbaHost _host;
}

For endpoints that stream indefinitely or require observing events mid-stream, use StreamServerSentEvents instead of Scenario. This method returns as soon as response headers arrive and does not buffer the response body.

Key Behaviors:

• Consumption: Use stream.ReadEvents(token) or stream.ReadEvents<T>(token) to yield events as the application writes them. The stream can only be consumed once.
• Cancellation: Disposing the SseStreamResult aborts the in-flight request and triggers the endpoint's HttpContext.RequestAborted token.
• Lifecycle: BeforeEach/BeforeEachAsync and security extensions (like JwtSecurityStub or WithClaim) work normally. However, AfterEach/AfterEachAsync actions run with a null HttpContext upon disposal.
• Limitations: Response assertions like ContentShouldContain or header assertions are not supported and will be rejected. You must assert on the streamed events themselves. The response must have the text/event-stream content type.

public async Task stream_live_events(IAlbaHost host)
{
    using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(10));

    // Returns as soon as the response headers arrive;
    // the response body is never buffered
    await using var stream = await host.StreamServerSentEvents(x =>
    {
        x.Get.Url("/sse/infinite");
    }, timeout.Token);

    // Events are yielded as the application writes them
    await foreach (var item in stream.ReadEvents(timeout.Token))
    {
        if (item.Data == "done") break;
    }

    // Disposing the stream aborts the request, cancelling the
    // endpoint's HttpContext.RequestAborted token
}