Using Testcontainers in .NET

In gitclub-dotnet I need a few services to run for the integration tests. In this article we will take a look at Testcontainers for .NET, which is ...

[...] a library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions. The library is built on top of the .NET Docker remote API and provides a lightweight implementation to support your test environment in all circumstances.

All code can be found in a Git repository at:

Using Testcontainers with MSTest

In the gitclub-dotnet we have already written a docker-compose.yaml file, which is responsible for spinning up a Postgres instance and OpenFGA containers.

version: '3.8'

networks:
  openfga:

services:
  postgres:
    image: postgres:16
    container_name: postgres
    networks:
      - openfga
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - "./postgres/postgres.conf:/usr/local/etc/postgres/postgres.conf"
      - ../sql/openfga.sql:/docker-entrypoint-initdb.d/1-openfga.sql
      - ../sql/gitclub.sql:/docker-entrypoint-initdb.d/2-gitclub.sql
      - ../sql/gitclub-versioning.sql:/docker-entrypoint-initdb.d/3-gitclub-versioning.sql
      - ../sql/gitclub-notifications.sql:/docker-entrypoint-initdb.d/4-gitclub-notifications.sql
      - ../sql/gitclub-replication.sql:/docker-entrypoint-initdb.d/5-gitclub-replication.sql
      - ../sql/gitclub-tests.sql:/docker-entrypoint-initdb.d/6-gitclub-tests.sql
      - ../sql/gitclub-data.sql:/docker-entrypoint-initdb.d/7-gitclub-data.sql
    command: "postgres -c config_file=/usr/local/etc/postgres/postgres.conf"
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
      interval: 5s
      timeout: 5s
      retries: 5

  migrate:
    depends_on:
      postgres:
        condition: service_healthy
    image: openfga/openfga:latest
    container_name: migrate
    command: migrate
    environment:
      - OPENFGA_DATASTORE_ENGINE=postgres
      - OPENFGA_DATASTORE_URI=postgres://postgres:password@postgres:5432/postgres?sslmode=disable&search_path=openfga
    networks:
      - openfga

  openfga:
    depends_on:
      migrate:
        condition: service_completed_successfully
    image: openfga/openfga:latest
    container_name: openfga
    environment:
      - OPENFGA_DATASTORE_ENGINE=postgres
      - OPENFGA_DATASTORE_URI=postgres://postgres:password@postgres:5432/postgres?sslmode=disable&search_path=openfga
      - OPENFGA_LOG_FORMAT=json
    command: run
    networks:
      - openfga
    ports:
      # Needed for the http server
      - "8080:8080"
      # Needed for the grpc server (if used)
      - "8081:8081"
      # Needed for the playground (Do not enable in prod!)
      - "3000:3000"
    healthcheck:
      test: ['CMD', '/usr/local/bin/grpc_health_probe', '-addr=openfga:8081']
      interval: 5s
      timeout: 30s
      retries: 3

  gitclub-fga-model-docker:
    depends_on:
      openfga:
        condition: service_healthy
    image: openfga/cli:latest
    container_name: gitclub-fga-model
    networks:
      - openfga
    volumes:
      - ../fga/gitclub.fga.yaml:/gitclub.fga.yaml
      - ../fga/gitclub-model.fga:/gitclub-model.fga
      - ../fga/gitclub-tuples.yaml:/gitclub-tuples.yaml
    command: store import --api-url http://openfga:8080 --file /gitclub.fga.yaml --store-id ${FGA_STORE_ID}

We now start the Testcontainers implementation by adding all files required by the Docker containers as a Link in our Solution. This has the nice side-effect, that you can use the files for both, the docker-compose.yaml and the Testcontainers.

Make sure to always copy the files to the output directory.

<Project Sdk="Microsoft.NET.Sdk">

  <!-- ... -->

  <ItemGroup>
    <Folder Include="Resources\docker\" />
    <Folder Include="Resources\fga\" />
    <Folder Include="Resources\sql\" />
  </ItemGroup>

  <ItemGroup>
    <None Include="..\..\docker\postgres\postgres.conf" Link="Resources\docker\postgres.conf">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\fga\gitclub-model.fga" Link="Resources\fga\gitclub-model.fga">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\fga\gitclub-tuples.yaml" Link="Resources\fga\gitclub-tuples.yaml">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\fga\gitclub.fga.yaml" Link="Resources\fga\gitclub.fga.yaml">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\sql\gitclub-data.sql" Link="Resources\sql\gitclub-data.sql">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\sql\gitclub-notifications.sql" Link="Resources\sql\gitclub-notifications.sql">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\sql\gitclub-replication.sql" Link="Resources\sql\gitclub-replication.sql">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\sql\gitclub-tests.sql" Link="Resources\sql\gitclub-tests.sql">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\sql\gitclub-versioning.sql" Link="Resources\sql\gitclub-versioning.sql">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\sql\gitclub.sql" Link="Resources\sql\gitclub.sql">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
    <None Include="..\..\sql\openfga.sql" Link="Resources\sql\openfga.sql">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
  </ItemGroup>

  <!-- ... -->

</Project>

We can then create a class DockerContainers, which is basically a one to one translation from the docker-compose.yaml to the Testcontainers syntax.

Please note, that it only needs to be static, because of the MSTest lifecycle, which requires static methods for class and assembly level test initialization.

// Licensed under the MIT license. See LICENSE file in the project root for full license information.

using DotNet.Testcontainers.Builders;
using DotNet.Testcontainers.Configurations;
using DotNet.Testcontainers.Containers;
using DotNet.Testcontainers.Networks;

namespace GitClub.Tests
{
    public static class DockerContainers
    {
        public static INetwork OpenFgaNetwork = new NetworkBuilder()
            .WithName("openfga")
            .WithDriver(NetworkDriver.Bridge)
            .Build();

        public static IContainer PostgresContainer = new ContainerBuilder()
            .WithName("postgres")
            .WithImage("postgres:16")
            .WithNetwork(OpenFgaNetwork)
            .WithPortBinding(hostPort: 5432, containerPort: 5432)
            // Mount Postgres Configuration and SQL Scripts 
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/docker/postgres.conf"), "/usr/local/etc/postgres/postgres.conf")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/sql/openfga.sql"), "/docker-entrypoint-initdb.d/1-openfga.sql")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/sql/gitclub.sql"), "/docker-entrypoint-initdb.d/2-gitclub.sql")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/sql/gitclub-versioning.sql"), "/docker-entrypoint-initdb.d/3-gitclub-versioning.sql")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/sql/gitclub-notifications.sql"), "/docker-entrypoint-initdb.d/4-gitclub-notifications.sql")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/sql/gitclub-replication.sql"), "/docker-entrypoint-initdb.d/5-gitclub-replication.sql")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/sql/gitclub-tests.sql"), "/docker-entrypoint-initdb.d/6-gitclub-tests.sql")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/sql/gitclub-data.sql"), "/docker-entrypoint-initdb.d/7-gitclub-data.sql")
            // Set Username and Password
            .WithEnvironment(new Dictionary<string, string>
            {
                    {"POSTGRES_USER", "postgres" },
                    {"POSTGRES_PASSWORD", "password" },
            })
            // Start Postgres with the given postgres.conf.
            .WithCommand([
                "postgres",
                "-c",
                "config_file=/usr/local/etc/postgres/postgres.conf"
            ])
            // Wait until the Port is exposed.
            .WithWaitStrategy(Wait
                .ForUnixContainer()
                .UntilPortIsAvailable(5432))
            .Build();

        public static IContainer OpenFgaMigrateContainer = new ContainerBuilder()
            .WithName("openfga-migration")
            .WithImage("openfga/openfga:latest")
            .DependsOn(PostgresContainer)
            .WithNetwork(OpenFgaNetwork)
            .WithEnvironment(new Dictionary<string, string>
            {
                {"OPENFGA_DATASTORE_ENGINE", "postgres" },
                {"OPENFGA_DATASTORE_URI", "postgres://postgres:password@postgres:5432/postgres?sslmode=disable&search_path=openfga" }
            })
            .WithCommand("migrate")
            .Build();

        public static IContainer OpenFgaServerContainer = new ContainerBuilder()
            .WithName("openfga-server")
            .WithImage("openfga/openfga:latest")
            .DependsOn(OpenFgaMigrateContainer)
            .WithNetwork(OpenFgaNetwork)
            .WithCommand("run")
            .WithPortBinding(hostPort: 8080, containerPort: 8080)
            .WithPortBinding(hostPort: 8081, containerPort: 8081)
            .WithPortBinding(hostPort: 3000, containerPort: 3000)
            .WithEnvironment(new Dictionary<string, string>
            {
                {"OPENFGA_DATASTORE_ENGINE", "postgres" },
                {"OPENFGA_DATASTORE_URI", "postgres://postgres:password@postgres:5432/postgres?sslmode=disable&search_path=openfga" }
            })
            .WithWaitStrategy(Wait
                .ForUnixContainer()
                .UntilMessageIsLogged("HTTP server listening on '0.0.0.0:8080'.."))
            .Build();

        public static IContainer OpenFgaModelContainer = new ContainerBuilder()
            .WithName("openfga-model")
            .WithImage("openfga/cli:latest")
            .DependsOn(OpenFgaServerContainer)
            .WithNetwork(OpenFgaNetwork)
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/fga/gitclub.fga.yaml"), "/gitclub.fga.yaml")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/fga/gitclub-model.fga"), "/gitclub-model.fga")
            .WithBindMount(Path.Combine(Directory.GetCurrentDirectory(), "Resources/fga/gitclub-tuples.yaml"), "/gitclub-tuples.yaml")
            .WithCommand([
                "store",
                "import",
                "--api-url", "http://openfga-server:8080",
                "--file", "/gitclub.fga.yaml",
                "--store-id", "01HP82R96XEJX1Q9YWA9XRQ4PM"
            ])
            .Build();

        public static async Task StartAllContainersAsync()
        {
            await PostgresContainer.StartAsync();
            await OpenFgaMigrateContainer.StartAsync();
            await OpenFgaServerContainer.StartAsync();
            await OpenFgaModelContainer.StartAsync();
        }

        public static async Task StopAllContainersAsync()
        {
            await PostgresContainer.StopAsync();
            await OpenFgaMigrateContainer.StopAsync();
            await OpenFgaServerContainer.StopAsync();
            await OpenFgaModelContainer.StopAsync();
        }
    }
}

In the IntegrationTestBase, which is the base class for all integration tests to be written, we will then use DockerContainers in the assembly-level test initialization.

// Licensed under the MIT license. See LICENSE file in the project root for full license information.

// ...

namespace GitClub.Tests
{
    [TestClass]
    public abstract class IntegrationTestBase
    {
        // ...

        [AssemblyInitialize]
        public static async Task AssemblyInitializeAsync(TestContext context)
        {
            await DockerContainers.StartAllContainersAsync();
        }

        [AssemblyCleanup]
        public static async Task AssemblyCleanupAsync()
        {
            await DockerContainers.StopAllContainersAsync();
        }

        // ...
    }
}

Conclusion

And that's it. You will now see the Containers spinning up for the tests, so there's no need for manually running a docker-compose before executing the tests.

To get a more reliable container initialization sequence, you'll probably need better Wait Strategy, which is described in the Testcontainers documentation at:

Enjoy your integration tests!


How to contribute

One of the easiest ways to contribute is to participate in discussions. You can also contribute by submitting pull requests.

General feedback and discussions?

Do you have questions or feedback on this article? Please create an issue on the Repositories issue tracker.

Something is wrong or missing?

There may be something wrong or missing in this article. If you want to help fixing it, then please make a Pull Request to this file.