Fork me on GitHub

Alba 1.0.0


Next

Documentation

Previous

Alba

Getting Started


Alba itself is just a class library. All you really need to do to start with Alba is to install the Nuget to your testing project for your application like so:

PM> Install-Package Alba

Or, using paket:

paket add nuget Alba

How does Alba work?

Alba is a test helper within some kind of unit testing tool (xUnit, NUnit, etc) that provides a little help to bootstrap an ASP.Net Core application in memory the way that the application itself is configured and to subsequently execute and verify HTTP requests through the full application's middleware pipeline.

You can choose to spin up a Kestrel web host as part of bootstrapping a system with Alba, but the Alba Scenario's work by directly invoking the ASP.Net Core application's underlying RequestDelegate to exercise the full stack of middleware without actually making an HTTP request to a running web server.

Testing Hello, World

Now let's say that you built the obligatory hello world application for ASP.Net Core shown below:


public class Startup
{
    public void Configure(IApplicationBuilder builder)
    {
        builder.Run(context =>
        {
            context.Response.Headers["content-type"] = "text/plain";
            return context.Response.WriteAsync("Hello, World!");
        });
    }
}

We can now use Alba to declare an integration test for our Hello, World application within an xUnit testing project:


[Fact]
public Task should_say_hello_world()
{
    using (var system = SystemUnderTest.ForStartup<Startup>())
    {
        // This runs an HTTP request and makes an assertion
        // about the expected content of the response
        return system.Scenario(_ =>
        {
            _.Get.Url("/");
            _.ContentShouldBe("Hello, World!");
            _.StatusCodeShouldBeOk();
        });
    }
}

The sample up above bootstraps the application defined by our Startup and executes a Scenario against the running system. A Scenario in Alba defines how the HTTP request should be constructed (the request body, headers, url) and optionally gives you the ability to express assertions against the expected HTTP response.

Alba comes with plenty of helpers in its fluent interface to work with the HttpRequest and HttpResponse, or you can work directly with the underlying ASP.Net Core objects:


[Fact]
public async Task should_say_hello_world_with_raw_objects()
{
    using (var system = SystemUnderTest.ForStartup<Startup>())
    {
        var response = await system.Scenario(_ =>
        {
            _.Get.Url("/");
            _.StatusCodeShouldBeOk();
        });

        response.ResponseBody.ReadAsText()
            .ShouldBe("Hello, World!");

        // or you can go straight at the HttpContext
        // The ReadAllText() extension method is from Baseline


        var body = response.Context.Response.Body;
        body.Position = 0; // need to rewind it because we read it above
        body.ReadAllText().ShouldBe("Hello, World!");
    }
}

Do note that Alba is not directly coupled to xUnit and would be usable within any .Net unit testing library.

To see where to go from here, see the Documentation