github.com/testcontainers/testcontainers-go - Connected to docker: 
  Server Version: 28.3.0
  API Version: 1.48
  Operating System: Docker Desktop
  Total Memory: 7836 MB
//.....
🐳 Creating container for image mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
🐳 Creating container for image testcontainers/ryuk:0.11.0
✅ Container created: 5e43ec4bd8ea
🐳 Starting container: 5e43ec4bd8ea
✅ Container started: 5e43ec4bd8ea
⏳ Waiting for container id 5e43ec4bd8ea image: testcontainers/ryuk:0.11.0. Waiting for: &{Port:8080/tcp timeout:<nil> PollInterval:100ms skipInternalCheck:false}
🔔 Container is ready: 5e43ec4bd8ea
✅ Container created: cb1d2abb7255
🐳 Starting container: cb1d2abb7255
✅ Container started: cb1d2abb7255
⏳ Waiting for container id cb1d2abb7255 image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview. Waiting for: &{Port:8081 timeout:<nil> PollInterval:100ms skipInternalCheck:false}
🔔 Container is ready: cb1d2abb7255
=== RUN   TestCreateItem
--- PASS: TestCreateItem (0.00s)
=== RUN   TestCreateItem_FailureScenarios
//.....
--- PASS: TestCreateItem_FailureScenarios (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/missing_name (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/missing_category (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/invalid_JSON (0.00s)
    --- PASS: TestCreateItem_FailureScenarios/wrong_HTTP_method (0.00s)
=== RUN   TestGetItem
--- PASS: TestGetItem (0.00s)
=== RUN   TestGetItem_FailureScenarios
//....
--- PASS: TestGetItem_FailureScenarios (0.00s)
    --- PASS: TestGetItem_FailureScenarios/missing_item_ID (0.00s)
    --- PASS: TestGetItem_FailureScenarios/missing_category_parameter (0.00s)
    --- PASS: TestGetItem_FailureScenarios/empty_category_parameter (0.00s)
    --- PASS: TestGetItem_FailureScenarios/non-existent_item_ID (0.00s)
    --- PASS: TestGetItem_FailureScenarios/valid_item_ID_but_wrong_category (0.00s)
PASS
🐳 Stopping container: cb1d2abb7255
✅ Container stopped: cb1d2abb7255
🐳 Terminating container: cb1d2abb7255
🚫 Container terminated: cb1d2abb7255
ok      demo    9.194s

Understanding the test flow

The output shows how testcontainers orchestrates the entire process in three distinct phases:

• Container Setup Phase: testcontainers connects to Docker, starts the emulator and Ryuk containers, and waits until the emulator is ready for use.
• Test Execution Phase: Integration tests run against the live container, covering both successful operations and various error scenarios to ensure robust handling.
• Cleanup Phase: All containers are automatically stopped and removed, ensuring the system is left clean with no lingering resources.

The combination of testcontainers and the emulator gives you the reliability of testing against services without the operational overhead of managing test infrastructure. Every test run is isolated, repeatable, and starts from a known clean state. It gives you fast feedback while maintaining the confidence that comes from testing against actual database behavior.

Deep dive

Now let’s examine how this works by walking through the code and exploring the key components that make this work.

Orchestrating the test environment

The TestMain function serves as the entry point for our test suite, providing a way to perform setup and teardown operations that span multiple test functions. Unlike individual test functions that run in isolation, TestMain runs once per package and gives you control over the entire test execution lifecycle.

func TestMain(m *testing.M) {
    // Set up the CosmosDB emulator container
    ctx := context.Background()

    var err error
    emulator, err = setupCosmosDBEmulator(ctx)
    if err != nil {
        fmt.Printf("Failed to set up CosmosDB emulator: %v\n", err)
        os.Exit(1)
    }

    // ... client setup and data seeding

    // Run the tests
    code := m.Run()

    // Cleanup
    if emulator != nil {
        _ = emulator.Terminate(ctx)
    }

    os.Exit(code)
}

This structure ensures that the expensive operation of starting a Docker container happens only once, while all individual tests can run against the same container instance. The pattern is particularly valuable when your setup involves external resources like databases or message brokers.

Setting up the Azure Cosmos DB emulator

The setupCosmosDBEmulator function encapsulates the logic for creating and starting the emulator:

func setupCosmosDBEmulator(ctx context.Context) (testcontainers.Container, error) {

    req := testcontainers.ContainerRequest{
        Image:        emulatorImage,
        ExposedPorts: []string{emulatorPort + ":8081"},
        WaitingFor:   wait.ForListeningPort(nat.Port(emulatorPort)),
        Env: map[string]string{
            "ENABLE_EXPLORER": "false",
            "PROTOCOL":        "https",
        },
    }

    container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
        ContainerRequest: req,
        Started:          true,
    })

    // Give the emulator a bit more time to fully initialize
    time.Sleep(5 * time.Second)

    return container, nil
}

The ContainerRequest struct defines everything testcontainers needs to know about our desired container. The ExposedPorts field maps the container’s internal port 8081 to the same port on the host, while WaitingFor ensures testcontainers doesn’t consider the container ready until the emulator is actually listening on that port. The environment variables configure the emulator to run in HTTPS (PROTOCOL) mode without the web-based data explorer (ENABLE_EXPLORER is set to false). I encourage you to explore the documentation for more configuration options that might suit your testing needs.

Connecting to the emulator

The auth.GetEmulatorClientWithAzureADAuth function is part of the cosmosdb-go-sdk-helper package. It provides a convenient way to create a Azure Cosmos DB client that uses Microsoft Entra ID authentication, which is the recommended approach for production applications. However, in this test setup, GetEmulatorClientWithAzureADAuth creates a client instance configured specifically for the emulator environment. By passing the custom transport through the ClientOptions, we ensure that the SDK can successfully connect to the emulator despite its self-signed certificate.

transport := &http.Client{Transport: &http.Transport{
    TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
}}

options := &azcosmos.ClientOptions{ClientOptions: azcore.ClientOptions{
    Transport: transport,
}}

client, err = auth.GetEmulatorClientWithAzureADAuth(emulatorEndpoint, options)