Background & Introduction

Have you ever got frustrated by the amount of the work to be done to setup and manage a proper environment for testing your app? What if i told you that there is a tool that helps you to automate creation and managing a portion of your environment? Combined with tools like appium, playwrite, xUnit, Gherkins and CI platforms you can achieve and almost 100% automated test pipeline

Testcontainers is an open source framework for providing throwaway, lightweight instances of databases, message brokers, web browsers, or just about anything that can run in a Docker container.

--testcontainers.com

It's probably obvious that you always can always try automating docker commands trough cli using projects like CliWrap yourself! But why bother if there is a polished tool to do this with clean api?

Example

Imagine following Gherkins scenario

Feature: User should be able to check his/her todo lists:
  Given a User is already available in database:
  | Username  | Password  | Email             |
  | JohnDoe   | 1234Abcd% | JohnDoe@localhost |
  Given 'JohnDoe' has following todo lists
  | Checked | Title                   |
  | false   | Buy dinner ingredients  |
  | false   | Buy lunch ingredients   |
  When User checks the following item
  | Title                   |
  | Buy dinner ingredients  |
  Then `JohnDoe`'s todo list should be like this
  | Checked | Title                   |
  | true   | Buy dinner ingredients   |
  | false   | Buy lunch ingredients   |

lets consider traditional manual test env setup, then you have to manually configure the database before executing the test. and you have to reset the database manually to it's original state so that the test case would not fail. this could be easy if we're using in-memory/mocked databases as these are easy disposable db's. but what about web/mobile ui tests?

1. Setup test db
2. Setup test backend
3. Setup frontend
4. Run the scenario

It already looks boring and repetitive right? can't even imagine implementing other infrastructure (RabbitMQ, Redis, Other BlackBox Service, etc). that's where test-containers come in! lets look at a simple example from test-containers website it self:

// Create a new instance of a container.
var container = new ContainerBuilder()
  // Set the image for the container to "testcontainers/helloworld:1.1.0".
  .WithImage("testcontainers/helloworld:1.1.0")
  // Bind port 8080 of the container to a random port on the host.
  .WithPortBinding(8080, true)
  // Wait until the HTTP endpoint of the container is available.
  .WithWaitStrategy(Wait.ForUnixContainer().UntilHttpRequestIsSucceeded(r => r.ForPort(8080)))
  // Build the container configuration.
  .Build();

// Start the container.
await container.StartAsync()
  .ConfigureAwait(false);

// Create a new instance of HttpClient to send HTTP requests.
var httpClient = new HttpClient();

// Construct the request URI by specifying the scheme, hostname, assigned random host port, and the endpoint "uuid".
var requestUri = new UriBuilder(Uri.UriSchemeHttp, container.Hostname, container.GetMappedPublicPort(8080), "uuid").Uri;

// Send an HTTP GET request to the specified URI and retrieve the response as a string.
var guid = await httpClient.GetStringAsync(requestUri)
  .ConfigureAwait(false);

// Ensure that the retrieved UUID is a valid GUID.
Debug.Assert(Guid.TryParse(guid, out _));

hmm, it's running a docker container with testcontainers/helloworld:1.1.0 image, that exposes something in port 8080 wait is that an option to assign a random, available port? actually yes, this test-container thing looks really amazing already by sparing me to avoid implementing the logic to find and assign a random port to my container! and dont get me started with the wait strategy to wait until the port is available! in other words wait until the container is ready! then create an http client and call an http-request to the exposed port if the response is a valid guid tests is considered as passed! it's really allowing me to focus on implementing the test instead of the infrastructure needed by tests!

lets implement our own scenario!

Our own example:

lets implement our own todo-list example!

Domain & DbInfra

We have a users table and a todo-item table i think the tables are self explanatory. also we are using microsoft's builtin identity!

public record TodoItem
{
    public int Id { get; set; }
    public string Title { get; set; }
    public bool IsComplete { get; set; }
    public string UserId { get; set; }
    public IdentityUser User { get; set; }
}

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems { get; set; }
}

ApiHost

We are using postgres and we have crud endpoints for todo-items and register / login endpoints

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));


var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/todos", async (UserManager<IdentityUser> userManager, HttpContext httpContext, ApplicationDbContext dbContext) =>
{
...
}).RequireAuthorization();

app.MapGet("/todos/{id}", async (int id, UserManager<IdentityUser> userManager, HttpContext httpContext, ApplicationDbContext dbContext) =>
{
...
}).RequireAuthorization();

app.MapPost("/todos", async (TodoItem todo, UserManager<IdentityUser> userManager, HttpContext httpContext, ApplicationDbContext dbContext) =>
{
...
}).RequireAuthorization();

app.MapPut("/todos/{id}", async (int id, TodoItem updatedTodo, UserManager<IdentityUser> userManager, HttpContext httpContext, ApplicationDbContext dbContext) =>
{
...
}).RequireAuthorization();

app.MapDelete("/todos/{id}", async (int id, UserManager<IdentityUser> userManager, HttpContext httpContext, ApplicationDbContext dbContext) =>
{
...
}).RequireAuthorization();

app.MapPost("/register", async (UserManager<IdentityUser> userManager, RegisterModel model) =>
{
...
});

app.MapPost("/login", async (UserManager<IdentityUser> userManager, SignInManager<IdentityUser> signInManager, LoginModel model) =>
{
...
});

app.Run();

record RegisterModel
{
    public string Username { get; set; }
    public string Email { get; set; }
    public string Password { get; set; }
}

record LoginModel
{
    public string Username { get; set; }
    public string Password { get; set; }
}

front-end

We are using a blazorwasm frontend for this example

Pages/Login.razor
Pages/Register.razor
Components/TodoList.razor
Components/AddTodo.razor
App.razor
MainLayout.razor
appsettings.json

Prepare our blocks

ok now we need to Containerize different parts of our app! we'll lets consider these components

1. our db postgress
2. our backend todo-backend
3. our frontend todo-frontend

App Components... Assemble

see how easy it is to assemble our different components!

using System.Net.Http;
using System.Threading.Tasks;
using Testcontainers.PostgreSql;
using Testcontainers.Container.Abstractions.Hosting;
using Xunit;

public class TodoApiTests : IAsyncLifetime
{
    private readonly PostgreSqlContainer _postgresContainer;
    private readonly Container _backendContainer;
    private readonly Container _frontendContainer;
    private readonly HttpClient _httpClient;

    public TodoApiTests()
    {
        _postgresContainer = new PostgreSqlBuilder()
            .WithDatabase("TodoListDb")
            .WithUsername("yourusername")
            .WithPassword("yourpassword")
            .Build();

        _backendContainer = new ContainerBuilder()
            .WithImage("todo-backend")
            .WithPortBinding(80, true)
            .WithEnvironment("ConnectionStrings__DefaultConnection", _postgresContainer.GetConnectionString())
            .DependsOn(_postgresContainer)
            .Build();

        _frontendContainer = new ContainerBuilder()
            .WithImage("todo-frontend")
            .WithPortBinding(80, true)
            .DependsOn(_backendContainer)
            .WithEnvironment("Backend__Url", "http://todo-backend:80")
            .Build();

        _httpClient = new HttpClient();
    }

    public async Task InitializeAsync()
    {
        await _postgresContainer.StartAsync();
        await _backendContainer.StartAsync();
        await _frontendContainer.StartAsync();
    }

    public async Task DisposeAsync()
    {
        await _frontendContainer.StopAsync();
        await _backendContainer.StopAsync();
        await _postgresContainer.StopAsync();
    }

    [Fact]
    public async Task TestTodoApi()
    {
        var backendPort = _backendContainer.GetMappedPort(80);
        var frontendPort = _frontendContainer.GetMappedPort(80);

        var response = await _httpClient.GetAsync($"http://localhost:{frontendPort}/todos");
        response.EnsureSuccessStatusCode();
    }
}

future improvements:

as you can see setting up these components and testing different scenarios is a piece of cake thanks to test containers! you can use what ever tool you like to test anything with test containers and automate it using CI tools no more broken features in your app, YEAY!!