Alba is a helper library for doing automated testing against ASP.Net Core web services. Alba started out as a subsystem of the defunct FubuMVC project for HTTP contract testing, but was later extracted into its own project distributed via Nuget, ported to ASP.Net Core, and finally re-wired to incorporate TestServer internally.
There are certainly other advantages, but I think the biggest selling point of adopting ASP.Net Core is the ability to run HTTP requests through your system completely in memory without any other kind of external web server setup. In my experience, this has made automated integration testing of ASP.Net Core applications far simpler compared to older versions of ASP.Net.
We could use FubuMVC’s OWIN support with or without Katana to perform the same kind of automated testing that I’m demonstrating here years ago, but hardly anyone ever used that and what I’m showing here is significantly easier to use.
Why not just use TestServer you ask? You certainly can, but Alba provides a lot of helper functionality around exercising HTTP web services that will make your tests much more readable and remove a lot of the repetitive coding you’d have to do with just using TestServer.
To demonstrate Alba, I published a small solution called AlbaIntegrationTesting to GitHub this morning.
Starting with a small web services application generated with the dotnet new webapi template, I added a small endpoint that we’ll later write specifications against:
public class Answers
{
public int Product { get; set; }
public int Sum { get; set; }
}
public class AdditionController : ControllerBase
{
[HttpGet("math/{one}/{two}")]
public Answers DoMath(int one, int two)
{
return new Answers
{
Product = one * two,
Sum = one + two
};
}
}
Next, I added a new test project using xUnit.Net with the dotnet new xunit template. With the new skeleton testing project I:
- Added a reference to the latest Alba Nuget
- My preference for testing assertions in .Net is Shouldly, so I added a Nuget reference for that as well
Since bootstrapping an ASP.Net Core system is non-trivial in terms of performance, I utilized xUnit.Net’s support for sharing context between tests so that the application only has to be spun up once in the test suite. The first step of that is to create a new “fixture” class that holds the ASP.Net Core system in memory like so:
public class AppFixture : IDisposable
{
public AppFixture()
{
// Use the application configuration the way that it is in the real application
// project
var builder = Program.CreateHostBuilder(new string[0])
// You may need to do this for any static
// content or files in the main application including
// appsettings.json files
// DirectoryFinder is an Alba helper
.UseContentRoot(DirectoryFinder.FindParallelFolder("WebApplication"))
// Override the hosting environment to "Testing"
.UseEnvironment("Testing");
// This is the Alba scenario wrapper around
// TestServer and an active .Net Core IHost
System = new SystemUnderTest(builder);
// There's also a BeforeEachAsync() signature
System.BeforeEach(httpContext =>
{
// Take any kind of setup action before
// each simulated HTTP request
// In this case, I'm setting a fake JWT token on each request
// as a demonstration
httpContext.Request.Headers["Authorization"] = $"Bearer {generateToken()}";
});
System.AfterEach(httpContext =>
{
// Take any kind of teardown action after
// each simulated HTTP request
});
}
private string generateToken()
{
// In a current project, we implement this method
// to create a valid JWT token with the claims that
// the web services require
return "Fake";
}
public SystemUnderTest System { get; }
public void Dispose()
{
System?.Dispose();
}
}
This new AppFixture class will only be built once by xUnit.Net and shared between test unit classes using the IClassFixture<AppFixture> interface.
Do note that you can express some actions in Alba to take immediately before or after executing an HTTP request through your system for typical setup or teardown operations. In one of my current projects, we exploit this capability to add a pre-canned JWT to the request headers that’s required by our system. In our case, that’s allowing us to test the security integration and the multi-tenancy support that depends on the JWT claims at the same time we’re exercising controller actions and the associated database access underneath it. If you’re familiar with the test pyramid idea, these tests are the middle layers of our testing pyramid.
To simplify the xUnit.Net usage throughout the testing suite, I like to introduce a base class that inevitable accumulates utility methods for running Alba or common database setup and teardown functions. I tend to call this class IntegrationContext and here’s a sample:
public abstract class IntegrationContext : IClassFixture<AppFixture>
{
protected IntegrationContext(AppFixture fixture)
{
Fixture = fixture;
}
public AppFixture Fixture { get; }
/// <summary>
/// Runs Alba HTTP scenarios through your ASP.Net Core system
/// </summary>
/// <param name="configure"></param>
/// <returns></returns>
protected Task<IScenarioResult> Scenario(Action<Scenario> configure)
{
return Fixture.System.Scenario(configure);
}
// The Alba system
protected SystemUnderTest System => Fixture.System;
// Just a convenience because you use it pretty often
// in tests to get at application services
protected IServiceProvider Services => Fixture.System.Services;
}
Now with the AppFixture and IntegrationContext in place, let’s write some specifications against the AdditionController endpoint shown earlier in this post:
public class DoMathSpecs : IntegrationContext
{
public DoMathSpecs(AppFixture fixture) : base(fixture)
{
}
// This specification uses the shorthand helpers in Alba
// that's useful when you really only care about the data
// going in or out of the HTTP endpoint
[Fact]
public async Task do_some_math_adds_and_multiples_shorthand()
{
var answers = await System.GetAsJson<Answers>("/math/3/4");
answers.Sum.ShouldBe(7);
answers.Product.ShouldBe(12);
}
// This specification shows the longhand way of executing an
// Alba scenario and using some of its declarative assertions
// about the expected HTTP response
[Fact]
public async Task do_some_math_adds_and_multiples_longhand()
{
var result = await Scenario(x =>
{
x.Get.Url("/math/3/4");
x.ContentTypeShouldBe("application/json; charset=utf-8");
});
var answers = result.ResponseBody.ReadAsJson<Answers>();
answers.Sum.ShouldBe(7);
answers.Product.ShouldBe(12);
}
}
Alba can do a lot more to work with the HTTP requests and responses, but I hope this gives you a quick introduction to using Alba for integration testing.
The Shade Tree Developer 