Azure Functions Integration Testing With Testcontainers
As developers, we want reassurance that our code functions as expected. We also want to be given that reassurance as fast as possible. This is why we are writing automated tests. We also desire for those tests to be easy to run on our machine or in the worst-case scenario on the build agent as part of the continuous integration pipeline. This is something that can be challenging to achieve when it comes to Azure Functions.
Depending on the language we are using for our Azure Functions, the challenges can be different. Let's take .NET (I guess I haven't surprised anyone with that choice) as an example. In the case of .NET, we can write any unit tests we want (I will deliberately avoid trying to define what is that unit). But the moment we try to move to integration tests, things get tricky. If our Azure Function is using the in-process model, we have an option of crafting a system under test based on the WebJobs host which will be good enough for some scenarios. If our Azure Function is using the isolated worker model there are only two options: accept that our tests will integrate only to a certain level and implement Test Doubles or wait for the Azure Functions team to implement a test worker. This is all far from perfect.
To work around at least some of the above limitations, I've adopted with my teams a different approach for Azure Functions integration testing - we've started using Testcontainers. Testcontainers is a framework for defining through code throwaway, lightweight instances of containers, to be used in test context.
We initially adopted this approach for .NET Azure Functions, but I know that teams creating Azure Functions in different languages also started using it. This is possible because the approach is agnostic to the language in which the functions are written (and the tests can be written using any language/framework supported by Testcontainers).
In this post, I want to share with you the core parts of this approach. It starts with creating a Dockerfile for your Azure Functions.
Creating a Dockerfile for an Azure Functions Container Image
You may already have a Dockerfile for your Azure Functions (for example if you decided to host them in Azure Container Apps or Kubernetes). From my experience, that's usually not the case. That means you need to create a Dockerfile. There are two options for doing that. You can use Azure Functions Core Tools and call func init with the --docker-only option, or you can create the Dockerfile manually. The Dockerfile is different for every language, so until you gain experience I suggest using the command. Once you are familiar with the structure, you will very likely end up with a modified template that you will be reusing with small adjustments. The one below is my example for .NET Azure Functions using the isolated worker model.
FROM mcr.microsoft.com/dotnet/sdk:7.0 AS installer-env
ARG RESOURCE_REAPER_SESSION_ID="00000000-0000-0000-0000-000000000000"
LABEL "org.testcontainers.resource-reaper-session"=$RESOURCE_REAPER_SESSION_ID
WORKDIR /src
COPY function-app/ ./function-app/
RUN dotnet publish function-app \
--output /home/site/wwwroot
FROM mcr.microsoft.com/azure-functions/dotnet-isolated:4-dotnet-isolated7.0
ENV AzureWebJobsScriptRoot=/home/site/wwwroot \
AzureFunctionsJobHost__Logging__Console__IsEnabled=true
COPY --from=installer-env ["/home/site/wwwroot", "/home/site/wwwroot"]
What's probably puzzling you right now is that label based on the provided argument. This is something very specific to Testcontainers. The above Dockerfile is for a multi-stage build, so it will generate intermediate layers. Testcontainers has a concept of Resource Reaper which job is to remove Docker resources once they are no longer needed. This label is needed for the Resource Reaper to be able to track those intermediate layers.
Once we have the Dockerfile we can create the test context.
Creating a Container Instance in Test Context
The way you create the test context depends on the testing framework you are going to use and the isolation strategy you want for that context. My framework of choice is xUnit. When it comes to the isolation strategy, it depends 😉. That said, the one I'm using most often is test class. For xUnit that translates to class fixture. You can probably guess that there are also requirements when it comes to the context lifetime management. After all, we will be spinning containers and that takes time. That's why the class fixture must implement IAsyncLifetime to provide support for asynchronous operations.
public class AzureFunctionsTestcontainersFixture : IAsyncLifetime
{
...
public AzureFunctionsTestcontainersFixture()
{
...
}
public async Task InitializeAsync()
{
...
}
public async Task DisposeAsync()
{
...
}
}
There are a couple of things that we need to do here. The first is creating an image based on our Dockerfile. For this purpose, we can use ImageFromDockerfileBuilder. The minimum we need to provide is the location of the Dockerfile (directory and file name). Testcontainers provides us with some handy helpers for getting the solution, project, or Git directory. We also want to set that RESOURCE_REAPER_SESSION_ID argument.
public class AzureFunctionsTestcontainersFixture : IAsyncLifetime
{
private readonly IFutureDockerImage _azureFunctionsDockerImage;
public AzureFunctionsTestcontainersFixture()
{
_azureFunctionsDockerImage = new ImageFromDockerfileBuilder()
.WithDockerfileDirectory(CommonDirectoryPath.GetSolutionDirectory(), String.Empty)
.WithDockerfile("AzureFunctions-Testcontainers.Dockerfile")
.WithBuildArgument(
"RESOURCE_REAPER_SESSION_ID",
ResourceReaper.DefaultSessionId.ToString("D"))
.Build();
}
public async Task InitializeAsync()
{
await _azureFunctionsDockerImage.CreateAsync();
...
}
...
}
With the image in place, we can create a container instance. This will require reference to the image, port binding, and wait strategy. Port binding is something that Testcontainers can almost completely handle for us. We just need to tell which port to bind and the host port can be assigned randomly. The wait strategy is quite important. This is how the framework knows that the container instance is available. We have a lot of options here: port availability, specific message in log, command completion, file existence, successful request, or HEALTHCHECK. What works great for Azure Functions is a successful request to its default page.
public class AzureFunctionsTestcontainersFixture : IAsyncLifetime
{
private readonly IFutureDockerImage _azureFunctionsDockerImage;
public IContainer AzureFunctionsContainerInstance { get; private set; }
...
public async Task InitializeAsync()
{
await _azureFunctionsDockerImage.CreateAsync();
AzureFunctionsContainerInstance = new ContainerBuilder()
.WithImage(_azureFunctionsDockerImage)
.WithPortBinding(80, true)
.WithWaitStrategy(
Wait.ForUnixContainer()
.UntilHttpRequestIsSucceeded(r => r.ForPort(80)))
.Build();
await AzureFunctionsContainerInstance.StartAsync();
}
...
}
The last missing part is the cleanup. We should nicely dispose the container instance and the image.
public class AzureFunctionsTestcontainersFixture : IAsyncLifetime
{
private readonly IFutureDockerImage _azureFunctionsDockerImage;
public IContainer AzureFunctionsContainerInstance { get; private set; }
...
public async Task DisposeAsync()
{
await AzureFunctionsContainerInstance.DisposeAsync();
await _azureFunctionsDockerImage.DisposeAsync();
}
}
Now we are ready to write some tests.
Implementing Integration Tests
At this point, we can start testing our function. We need a test class using our class fixture.
public class AzureFunctionsTests : IClassFixture<AzureFunctionsTestcontainersFixture>
{
private readonly AzureFunctionsTestcontainersFixture _azureFunctionsTestcontainersFixture;
public AzureFunctions(AzureFunctionsTestcontainersFixture azureFunctionsTestcontainersFixture)
{
_azureFunctionsTestcontainersFixture = azureFunctionsTestcontainersFixture;
}
...
}
Now for the test itself, let's assume that the function has an HTTP trigger. To build the URL of our function we can use the Hostname provided by the container instance and acquire the host port by calling .GetMappedPublicPort. This means that the test only needs to create an instance of HttpClient, make a request, and assert the desired aspects of the response. The simplest test I could think of was to check for a status code indicating success.
public class AzureFunctionsTests : IClassFixture<AzureFunctionsTestcontainersFixture>
{
private readonly AzureFunctionsTestcontainersFixture _azureFunctionsTestcontainersFixture;
...
[Fact]
public async Task Function_Request_ReturnsResponseWithSuccessStatusCode()
{
HttpClient httpClient = new HttpClient();
var requestUri = new UriBuilder(
Uri.UriSchemeHttp,
_azureFunctionsTestcontainersFixture.AzureFunctionsContainerInstance.Hostname,
_azureFunctionsTestcontainersFixture.AzureFunctionsContainerInstance.GetMappedPublicPort(80),
"api/function"
).Uri;
HttpResponseMessage response = await httpClient.GetAsync(requestUri);
Assert.True(response.IsSuccessStatusCode);
}
}
And Voila. This will run on your machine (assuming you have Docker) and in any CI/CD environment which build agents have Docker pre-installed (for example Azure DevOps or GitHub).
Adding Dependencies
What I've shown you so far covers the scope of the function itself. This is already beneficial because it allows for verifying if dependencies are registered properly or if the middleware pipeline behaves as expected. But Azure Functions rarely exist in a vacuum. There are almost always dependencies and Testcontainers can help us with those dependencies as well. There is a wide set of preconfigured implementations that we can add to our test context. A good example can be storage. In the majority of cases, storage is required to run the function itself. For local development, Azure Functions are using the Azurite emulator and we can do the same with Testcontainers as it is available as a ready-to-use module. To add it to the context you just need to reference the proper NuGet package and add a couple of lines of code.
public class AzureFunctionsTestcontainersFixture : IAsyncLifetime
{
...
public AzuriteContainer AzuriteContainerInstance { get; private set; }
...
public async Task InitializeAsync()
{
AzuriteContainerInstance = new AzuriteBuilder().Build();
await AzuriteContainerInstance.StartAsync();
...
}
public async Task DisposeAsync()
{
...
await AzuriteContainerInstance.DisposeAsync();
}
}
We also need to point Azure Functions to use this Azurite container by setting the AzureWebJobsStorage parameter.
public class AzureFunctionsTestcontainersFixture : IAsyncLifetime
{
...
public async Task InitializeAsync()
{
...
AzureFunctionsContainerInstance = new ContainerBuilder()
...
.WithEnvironment("AzureWebJobsStorage", AzuriteContainerInstance.GetConnectionString())
...
.Build();
...
}
...
}
That's it. Having Azurite in place also enables testing functions that use triggers and bindings based on Azure Storage. There are also ready-to-use modules for Redis, Azure Cosmos DB, Azure SQL Edge, MS SQL, Kafka, or RabbitMQ. So there is quite good out-of-the-box coverage for potential Azure Functions dependencies. Some other dependencies can be covered by creating containers yourself (for example with an unofficial Azure Event Grid simulator). That said, some dependencies can be only satisfied by a real thing (at least for now).
A Powerful Tool in Your Toolbox
Is Testcontainers a solution for every integration problem - no. Should Testcontainers be your default choice when thinking about integration tests - also no. But it is a very powerful tool and you should be familiar with it, so you can use it when appropriate.
