Integration Testing in .NET Using Testcontainers (No Docker Drama, Even using CI)

Local config, test state pollution, and flaky mocks that don’t actually prove your code works.

I hit that wall myself. Then I discovered Testcontainers for .NET, and everything got easier.

This post shows how to use Testcontainers to spin up real services in your .NET tests (like PostgreSQL or Redis), and how to run everything smoothly in CI with zero Docker hassle.

Why Testcontainers?

Testcontainers gives you clean, throwaway Docker containers during test runs. That means:

You can test against real services (PostgreSQL, Redis, Kafka, whatever).
You don’t have to install or manage anything manually.
Your tests are isolated, reproducible, and easier to trust.

Best of all: it works exactly the same on your local machine and in CI.

Quick Setup in Your Test Project

First, install the core package:

dotnet add package Testcontainers

And yes — Docker needs to be installed and running. So install Docker Desktop if you haven't already.

Example: PostgreSQL in Your Test Suite

Here’s a simple test class that spins up PostgreSQL before your tests run and tears it down afterward:

using DotNet.Testcontainers.Builders;
using DotNet.Testcontainers.Containers;
using Xunit;

public class DatabaseTests : IAsyncLifetime
{
    private readonly PostgreSqlTestcontainer _pgContainer;

    public DatabaseTests()
    {
        _pgContainer = new TestcontainersBuilder<PostgreSqlTestcontainer>()
            .WithDatabase(new PostgreSqlTestcontainerConfiguration
            {
                Database = "testdb",
                Username = "postgres",
                Password = "password"
            })
            .Build();
    }

    public async Task InitializeAsync()
    {
        await _pgContainer.StartAsync();
        // Optionally run schema setup or seed data
    }

    public async Task DisposeAsync()
    {
        await _pgContainer.DisposeAsync();
    }

    [Fact]
    public async Task CanQueryDatabase()
    {
        var connectionString = _pgContainer.ConnectionString;

        // Use Dapper, EF Core, or plain ADO.NET to talk to the DB
        // Assert results as usual
    }
}

This is all it takes. No manual DB setup. No shared state between tests. Simple as that.

And Yes — It Works in CI Without Extra Docker Config

You might expect CI pipelines to need special setup for Docker-in-Docker. That used to be the case. Not anymore.

Testcontainers for .NET works out of the box with GitHub Actions and Azure Pipelines — no extra services, no Docker socket mounting, no "privileged mode" nonsense.

✅ GitHub Actions Example

name: .NET Testcontainers CI

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.0.x'

      - name: Restore dependencies
        run: dotnet restore

      - name: Run tests
        run: dotnet test --no-build --verbosity normal

That’s it. Docker is already installed and ready to go.

✅ Azure DevOps Example

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '8.0.x'

- script: dotnet restore
  displayName: 'Restore'

- script: dotnet build --no-restore
  displayName: 'Build'

- script: dotnet test --no-build --verbosity normal
  displayName: 'Test'

Again, nothing extra required. Microsoft-hosted agents include Docker by default.

For more info, see: Testcontainers CI guide

Final Thoughts

I’ve used Testcontainers in real-world projects where database state and integration mattered, and honestly? It’s a game changer. No more spending hours trying to get a local or CI DB spun up. No test-env drift. Just real, reliable integration tests.

If you’re writing any code that interacts with services, this should be your default test setup.

Let me know if you end up using it — happy to share tips or help debug setup issues.