👉🏼 Click here to Join I ❤️ .NET WhatsApp Channel to get 🔔 notified about new articles and other updates.
Using Docker Test Containers in Functional Testing in ASP.NET WEB API

Using Docker Test Containers in Functional Testing in ASP.NET WEB API


18 Articles


In this article, let's learn about testing with real database using Docker Test Containers in Web API in ASP.NET Core.

Note: If you have not done so already, I recommend you read the article on Functional testing your ASP.NET WEB API.

Table of Contents

  1. Introduction
  2. Why Docker Test Containers ?
  3. Steps to do Functional Test using Test Containers
  4. Advantages
  5. Summary


We are all aware that the softwares we build works rarely in isolation. Our apps will talk to many external systems like database, message brokers, web browsers, cloud services or just any other external systems. And validating the integration with these external systems is very important.

Testcontainers is a library that provides easy and lightweight APIs for bootstrapping local development and test dependencies with real services wrapped in Docker containers. Using Testcontainers, you can write tests that depend on the same services you use in production without mocks or in-memory services.

Why Docker Test Containers ?

Cloud-native infrastructure and microservices have taken control away from developers and made it painful to work locally. While you own only your Service and its datastore, you have several downstream dependencies that you need for local development and integration testing. This brings the following challenges:

  • Before running tests, you must ensure that the infrastructure is up and running and is pre-configured in a desired state.
  • If the resources (database, message broker, etc) are shared across multiple users or CI pipelines, then the test results are non-deterministic because of the possibility of data corruption and configuration drift.

A possible workaround could be using in-memory variations of the required services. But this is almost similar like using mocks. In-memory services might not have all the features of the production / real service amd they have their own problems.

Testcontainers solves this by using Docker to spin up real services for functional testing and helps executing reliable and repeatable tests by talking to those real services and providing a programmatic API for your test code.

Steps to do Functional Test using Test Containers

Let's learn how to do functional test using Test Containers in ASP.NET Web API. We will be using the same project we used in the previous article and try using test containers for database instead of in-memory database.

Note: Before we begin, I would like to highlight that we are going to use single database container for all tests in our project. And the reason for this is when we have 100 or 1000 tests then spinning 100 or 1000 containers will make your test agent to go down consuming all memory and CPU.

  1. Install Testcontainers.PostgreSql in your Functional Test Project
  2. Setup Database Fixture as shown below

    Code Sample - Database Fixture for Test Containers in Function Test in ASP.NET

    DatabaseFixture inherits from IAsyncLifetime initialises the database container using InitializeAsync() and cleans up the container after the end of test using DisposeAsync()

    We are also creating a FunctionalTestCollection to be used as ICollectionFixture<DatabaseFixture>.

  3. Update CustomWebApplicationFactory to replace WeatherForecastDbContext connection string with Test Container Connection String as shown below

    Code Sample - Customer Web APplication Factory with Test Containers in Function Test in ASP.NET

  4. Finally mark the test class with [Collection("Database Collection")] and inject the dbcontext inside test method add the data for test and assert the same data returned from endpoint in test as shown below.

    Code Sample - Testing against real database in Function Test in ASP.NET


The advantages of Test Containers are as follows,

  • On-demand isolated infrastructure provisioning
  • Consistent experience on both local and CI environments
  • Testing with real dependencies helps to catch bugs earlier
  • Light Weight
  • No Mocks or In-Memory setup which behaves differently than real ones
  • Easy to setup and automatic clean up


In this article, we learnt about testing with real dependencies using Docker Test Containers in functional testing in ASP.NET Web API. We learnt how to do that with ASP.NET functional test and understood its advantages. Hope you enjoyed reading it.

To learn more interesting things about .NET in a simple way, 👉🏼 Click here to Join I ❤️ .NET WhatsApp Channel for free to get 🔔 notified about new articles and other updates.

  • Webapi
  • Docker
  • Test Containers
  • Functional Testing