How to create and manage unit test resources (best practices)

[HofmeisterAn]

I'd like to share and discuss best practices and examples of how to create and manage Docker resources in unit tests with .NET Testcontainers. I see frequently questions where developers ask about common patterns. Furthermore, I noticed that some developers are not aware of the asynchronous API and the different ways to set up and cleanup fixtures in testing tools.

The example below uses xUnit.net. It creates and shares a fixture Volume among all unit tests. Each unit test creates a fresh Container instance. The first unit test executes a command inside the container. The second one sends a simple HTTP request to the container.

I've added comments to the important sections. This helps to understand the basic concept. .NET Testcontainers allows tests for all kinds of use cases. Let me know if you need further explanations or what best practices you are interested in?

// Use the xUnit.net `IAsyncLifetime` interface to create and delete resources asynchronous e.g. containers, networks, volumes, etc.
// The Resource Reaper deletes resources as fallback on Linux operating systems when tests fail. But it's still good practices to remove resources when they are not required anymore.
public sealed class Volume : IDockerVolume, IAsyncLifetime
{
  private readonly IDockerVolume volume = new TestcontainersVolumeBuilder()
    .WithName(Guid.NewGuid().ToString("D")) // Use random names to prevent name clashes.
    .Build();

  public string Name => this.volume.Name;

  public string Destination => $"/mnt/{this.volume.Name}";

  public Task CreateAsync(CancellationToken ct = default)
  {
    return this.volume.CreateAsync(ct);
  }

  public Task DeleteAsync(CancellationToken ct = default)
  {
    return this.volume.DeleteAsync(ct);
  }

  public Task InitializeAsync()
  {
    return this.CreateAsync();
  }

  public Task DisposeAsync()
  {
    return this.DeleteAsync();
  }
}

// Use the xUnit.net `IClassFixture<TFixture>` interface to share fixtures among all tests. Creating and deleting Docker resources is usually an expensive operation.
// Fixtures improve unit tests a lot. xUnit.net supports different ways to set up and cleanup code: https://xunit.net/docs/shared-context.
public sealed class Container : IClassFixture<Volume>, IAsyncLifetime, IDisposable
{
  private const int HttpPort = 80;

  private readonly string timestampFilePath;

  private readonly IDockerContainer container;

  private readonly IOutputConsumer consumer = Consume.RedirectStdoutAndStderrToStream(new MemoryStream(), new MemoryStream());

  public Container(Volume volume)
  {
    this.timestampFilePath = string.Join(Path.AltDirectorySeparatorChar, volume.Destination, "timestamp");
    this.container = new TestcontainersBuilder<TestcontainersContainer>()
      .WithImage("nginx")
      .WithCommand("/bin/sh", "-c", $"date +%s > \"{this.timestampFilePath}\" && nginx -g \"daemon off;\"") // Override the container CMD instruction (write a file and start nginx).
      .WithVolumeMount(volume, volume.Destination) // Assign and mount the volume fixture to the container.
      .WithPortBinding(HttpPort, true) // Bind the HTTP port to a random port to avoid clashes. If the port is not exposed by the Dockerfile, expose it with `WithExposedPort`.
      .WithOutputConsumer(this.consumer) // Assign the output consumer to redirect stdout and stderr to a different stream.
      .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilPortIsAvailable(HttpPort) // Wait until the HTTP port is available.
        .UntilMessageIsLogged(this.consumer.Stderr, "start worker processes")) // Wait until the message is written to the output consumer stream.
      .Build();
  }

  [Fact]
  public async Task CliCmdCatWritesTimestampToStdout()
  {
    var execResult = await this.container.ExecAsync(new[] { "cat", this.timestampFilePath })
      .ConfigureAwait(false);
    Assert.Equal(0, execResult.ExitCode);
    Assert.NotEmpty(execResult.Stdout);
    Assert.Empty(execResult.Stderr);
  }

  [Fact]
  public async Task HttpRequestResponseWithWelcomeMessage()
  {
    var requestUriBuilder = new UriBuilder("http", this.container.Hostname, this.container.GetMappedPublicPort(HttpPort)); // Get the random port that's mapped to the HTTP port.

    using (var httpClient = new HttpClient())
    {
      var response = await httpClient.GetAsync(requestUriBuilder.Uri)
        .ConfigureAwait(false);
      var body = await response.Content.ReadAsStringAsync()
        .ConfigureAwait(false);
      Assert.Contains("Welcome to nginx!", body);
    }
  }

  public Task InitializeAsync()
  {
    return this.container.StartAsync();
  }

  public Task DisposeAsync()
  {
    return this.container.DisposeAsync().AsTask();
  }

  public void Dispose()
  {
    this.consumer.Dispose();
  }
}

[facundoLecuna]

The documentation (https://dotnet.testcontainers.org/) isn't very explanatory. What is "TestcontainersVolumeBuilder" and what it does?

[HofmeisterAn]

It configures and creates a Docker volume to persist data. Do you need anything specific?

[facundoLecuna]

I have my test database in an docker image of sql server, what I want is to create a Test with Xunit.net where the database used by Entity Framework is the one in my image. All tutorials that I've seen are for testing using HttpClient by making an http request, but I only want to test from my Service layer.

[HofmeisterAn]

The ASP.NET Core Blazor example covers the Entity Framework together with a MSSQL container. Here is the in-process example.