All of my integration tests often use Testcontainers to quickly spin up external dependencies like PostgreSQL or RabbitMQ. It’s very useful for creating a quick, production-like environment.

But I was running into an issue where the ports of these Docker containers were not freeing up on subsequent runs in my GitHub Actions build pipeline and would see errors indicating the ports were already bound by Docker.

The issue could only be recreated locally if the integration tests ended prematurely and allowed me to see containers weren’t properly being disposed.

Properly dispose of your containers

Your integration test class should extend IAsyncLifetime, which will allow you to dispose of containers as the test ends:

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

I was calling await _dbContainer.StopAsync(); which would stop the container but fail to free up any resources.

Use a random port

When building your container, you can use the overload .WithPortBinding(PostgreSqlPort, /* assignRandomHostPort */ true)

var container = new PostgreSqlBuilder()
    .WithName(GetType().Name + Guid.NewGuid())
    .WithPortBinding(PostgreSqlPort, true)
    .Build();

This will map the Docker container’s port to a random port on the host to reduce the chance of a collision if a port was not freed up. Note that I occasionally found hard-coded ports to be useful as I could open up a connection to my Testcontainer to debug the data on it.

Tell your pipeline to purge Docker resources. WARNING: Risky?

Depending on your environment, be careful with this one. In my GitHub Actions CI pipeline that runs tests, at the end I run:

  - name: Cleanup
    run: docker system prune -a --volumes

This removes all Docker resources. I am on a GitHub hosted runner so I have no ties to machines that run the actions. Your situation may differ.