Introduction

Welcome back, intrepid tester! In our previous adventures, we mastered the art of spinning up a basic, generic container with Testcontainers. You now know that these disposable environments are a game-changer for reliable integration testing. But what if the “out-of-the-box” container isn’t quite what you need? What if you need a specific database version, a custom configuration, or particular network settings?

That’s where customization comes in! In this chapter, we’ll unlock the power of Testcontainers to tailor your containers precisely to your testing needs. We’ll explore how to pick the perfect Docker image, understand the magic behind port mapping, and configure your services using environment variables. Mastering these techniques is essential for simulating real-world scenarios and ensuring your tests are robust, accurate, and truly reflect your production environment. Get ready to personalize your testing playgrounds!

Why Customization Matters: Core Concepts

Imagine you’re testing an application that relies on a very specific version of PostgreSQL, or perhaps a Redis instance that requires a password. The default container might not cut it. Customizing your Testcontainers setup allows you to:

  • Mimic Production Environments: Use the exact Docker image versions and configurations your application expects.
  • Test Edge Cases: Configure services in ways that might expose specific bugs or behaviors.
  • Enhance Security (for tests): Pass credentials or sensitive configurations securely to your test containers.

Let’s break down the three fundamental pillars of container customization: Docker Images, Port Mapping, and Environment Variables.

Docker Images: Picking the Right Foundation

At the heart of every container is a Docker image. Think of an image as a blueprint for your container – it defines the operating system, installed software, and initial configuration.

What is it? A Docker image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries, and settings.

Why is it important?

  • Version Control: Just like your application code, dependencies have versions. Testing against postgres:latest might work today, but tomorrow latest could update and break your tests unexpectedly. Pinning to a specific version (e.g., postgres:15.5) ensures consistency.
  • Feature Sets: Different versions of software often come with different features or bug fixes. Using the correct version ensures your tests cover the features your application actually uses.
  • Reproducibility: A fundamental principle of good testing is reproducibility. Using a fixed image tag ensures that your tests run in the exact same environment every single time.

How it functions: When you tell Testcontainers to start a container, you provide an image name and optionally a tag (e.g., redis:7.2.4-alpine). Testcontainers then instructs Docker to pull this specific image if it’s not already cached locally, and then creates a container instance from it.

Port Mapping: Connecting to Your Container

Containers are isolated environments. While they run services internally on specific ports (e.g., PostgreSQL on 5432, Redis on 6379), your test code running on the host machine needs a way to talk to them. This is where port mapping comes in.

What is it? Port mapping (also known as port forwarding) is the process of mapping a port inside a container to a port on the host machine. When your host machine sends traffic to the mapped host port, Docker redirects it to the corresponding port inside the container.

Why is it important? It’s the bridge that allows your tests to communicate with the services running within the containers.

How it functions:

  • Container Port: This is the port inside the container where the service is listening. For PostgreSQL, it’s typically 5432. For Redis, 6379.
  • Host Port: This is the port on your machine that Docker makes available for you to connect to the container’s service.
  • Testcontainers’ Magic: Testcontainers typically performs dynamic port mapping. This means it picks a random, available port on your host machine to map to the container’s internal port.
    • Why random? To prevent port collisions! If you ran multiple test suites or even multiple containers of the same type, and they all tried to map to a fixed host port (like 5432), only one could succeed. Random ports ensure each container gets its own unique access point.
    • After starting the container, Testcontainers provides you with the dynamically assigned host port, which your test code then uses to connect.
  • When to expose? You explicitly tell Testcontainers which container ports your service will listen on using withExposedPorts (or equivalent). Testcontainers then handles mapping these to random host ports.

Environment Variables: Container Configuration on the Fly

Many Docker images are designed to be configured through environment variables. This is a common and flexible way to pass dynamic settings to applications running inside containers without rebuilding the image.

What is it? Environment variables are key-value pairs that are available to processes running within a container. They are typically used for configuration settings like database credentials, API keys, feature flags, or service URLs.

Why is it important?

  • Flexibility: You can change a container’s behavior or configuration without modifying the image itself.
  • Security: While not suitable for highly sensitive secrets in production (where secret management solutions are used), for local testing, they offer a convenient way to pass credentials or API keys.
  • Standard Practice: Many official Docker images (databases, message queues, etc.) rely heavily on environment variables for initial setup.

How it functions: You provide a set of key-value pairs to Testcontainers using methods like withEnv (or equivalent). Testcontainers then injects these variables into the container’s environment before it starts, allowing the entrypoint script or the application inside to read and use them for configuration.

Step-by-Step Implementation: Customizing a PostgreSQL Container

Let’s put these concepts into practice. We’ll set up a PostgreSQL container, explicitly define its image, tell Testcontainers which port to expose, and pass some crucial environment variables for database setup.

We’ll use postgres:15.5 as our target image and configure a specific database, username, and password.

1. Java (JUnit 5 with Testcontainers-Java)

Ensure you have Testcontainers Java library (e.g., org.testcontainers:testcontainers-bom:1.19.4 and org.testcontainers:postgresql:1.19.4) in your pom.xml or build.gradle as of February 2026.

// src/test/java/com/example/PostgreCustomizationTest.java
package com.example;

import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.Assertions.assertNotNull;

@Testcontainers
public class PostgreCustomizationTest {

    // 1. Declare the container with a specific image and customization
    // We use PostgreSQLContainer for convenience, but GenericContainer works too.
    @Container
    public static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15.5") // Specify image tag!
            .withDatabaseName("testdb")      // Sets POSTGRES_DB env var
            .withUsername("testuser")        // Sets POSTGRES_USER env var
            .withPassword("testpass")        // Sets POSTGRES_PASSWORD env var
            .withExposedPorts(5432);         // Explicitly tells Testcontainers to expose port 5432 internally

    private static Connection connection;

    @BeforeAll
    static void setup() throws SQLException {
        // The container starts automatically thanks to @Testcontainers and @Container
        // Now, we get the dynamically mapped port and construct the JDBC URL
        String jdbcUrl = postgres.getJdbcUrl();
        String username = postgres.getUsername();
        String password = postgres.getPassword();

        System.out.println("Connecting to PostgreSQL at: " + jdbcUrl);
        System.out.println("Username: " + username + ", Password: " + password);

        connection = DriverManager.getConnection(jdbcUrl, username, password);
        assertNotNull(connection, "Should be able to establish a connection");
        System.out.println("Successfully connected to the PostgreSQL container!");

        // Optional: Create a table and insert data to verify
        try (Statement statement = connection.createStatement()) {
            statement.execute("CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(255))");
            statement.execute("INSERT INTO users (name) VALUES ('Alice'), ('Bob')");
        }
    }

    @AfterAll
    static void teardown() throws SQLException {
        if (connection != null) {
            connection.close();
        }
        // Testcontainers automatically stops and removes the container
    }

    @Test
    void testUserCount() throws SQLException {
        try (Statement statement = connection.createStatement()) {
            ResultSet rs = statement.executeQuery("SELECT COUNT(*) FROM users");
            assertTrue(rs.next());
            System.out.println("User count: " + rs.getInt(1));
            assertTrue(rs.getInt(1) == 2, "Should have 2 users in the database");
        }
    }
}

Explanation for Java:

  1. new PostgreSQLContainer<>("postgres:15.5"): Here, we instantiate a PostgreSQLContainer. Crucially, we pass "postgres:15.5" to its constructor. This tells Testcontainers exactly which Docker image version to use.
  2. .withDatabaseName("testdb"), .withUsername("testuser"), .withPassword("testpass"): These fluent methods are specific to PostgreSQLContainer (and other specialized database containers). They internally set the correct environment variables (POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD) that the PostgreSQL Docker image uses for initial database setup. This is a clean way to configure common database settings.
  3. .withExposedPorts(5432): This line explicitly tells Testcontainers that the PostgreSQL service inside the container is listening on port 5432. Testcontainers will then find a random available host port and map it to the container’s 5432.
  4. postgres.getJdbcUrl(): Instead of hardcoding connection strings, we dynamically retrieve the JDBC URL. This URL is constructed by Testcontainers using the dynamically mapped host port, ensuring your connection string is always correct.
  5. postgres.getUsername() and postgres.getPassword(): Similar to the JDBC URL, Testcontainers provides methods to retrieve the configured username and password, which are then used to establish the connection. This eliminates hardcoding and makes your tests flexible.

2. Python (using testcontainers-python with pytest)

Ensure you have pytest and testcontainers-python (e.g., pytest-testcontainers>=4.14.1 and sqlalchemy) installed as of February 2026.

# tests/test_postgre_customization.py
import pytest
from testcontainers.postgres import PostgreSQLContainer
import sqlalchemy

# 1. Declare the container as a fixture
# We use PostgreSQLContainer for convenience
@pytest.fixture(scope="module")
def postgres_container():
    # Specify image tag, environment variables, and exposed ports
    with PostgreSQLContainer("postgres:15.5") \
            .with_database_name("testdb") \
            .with_user("testuser") \
            .with_password("testpass") \
            .with_exposed_ports(5432) as postgres: # Explicitly expose port 5432 internally
        postgres.start()
        print(f"PostgreSQL container started at: {postgres.get_connection_url()}")
        print(f"Host port mapped to 5432: {postgres.get_exposed_port(5432)}")
        yield postgres
    # Container automatically stopped and removed when exiting 'with' block

@pytest.fixture(scope="module")
def db_connection(postgres_container):
    # Get dynamic connection details
    connection_url = postgres_container.get_connection_url()
    engine = sqlalchemy.create_engine(connection_url)
    connection = engine.connect()

    # Create table and insert data
    connection.execute(sqlalchemy.text("CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(255))"))
    connection.execute(sqlalchemy.text("INSERT INTO users (name) VALUES ('Alice'), ('Bob')"))
    connection.commit() # Commit the changes

    yield connection
    connection.close()


def test_user_count(db_connection):
    result = db_connection.execute(sqlalchemy.text("SELECT COUNT(*) FROM users"))
    count = result.scalar() # Get the single scalar value from the result
    print(f"User count: {count}")
    assert count == 2, "Should have 2 users in the database"

    result = db_connection.execute(sqlalchemy.text("SELECT name FROM users WHERE id = 1"))
    name = result.scalar()
    print(f"User with ID 1: {name}")
    assert name == "Alice"

Explanation for Python:

  1. PostgreSQLContainer("postgres:15.5"): Similar to Java, we pass the desired image tag directly to the constructor of the PostgreSQLContainer class.
  2. .with_database_name("testdb"), .with_user("testuser"), .with_password("testpass"): These methods, part of the PostgreSQLContainer (and other specialized Testcontainers Python modules), are convenient wrappers that set the necessary environment variables (POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD) for the PostgreSQL Docker image.
  3. .with_exposed_ports(5432): This tells Testcontainers that the internal port 5432 needs to be exposed, and Testcontainers will map it to a random host port.
  4. postgres.start(): We explicitly start the container in Python using start(). The with statement ensures stop() is called automatically.
  5. postgres.get_connection_url(): This method dynamically provides the full connection string, including the dynamically mapped host port, making your database connection robust.
  6. postgres.get_exposed_port(5432): You can retrieve the specific host port that was mapped to the container’s internal port 5432.

3. JavaScript/TypeScript (using testcontainers-node)

Ensure you have testcontainers (e.g., testcontainers:^10.8.0 for Node.js v18.x or later) and a database client like pg installed as of February 2026.

// test/postgre-customization.test.ts
import { GenericContainer, StartedTestContainer } from "testcontainers";
import { Client } from "pg"; // PostgreSQL client for Node.js

describe("PostgreSQL Customization", () => {
  let postgresContainer: StartedTestContainer;
  let pgClient: Client;

  beforeAll(async () => {
    // 1. Declare the container with specific image, env vars, and exposed ports
    // We use GenericContainer and set env vars directly for more control
    postgresContainer = await new GenericContainer("postgres:15.5") // Specify image tag!
      .withEnv({
        POSTGRES_DB: "testdb",      // Set database name via environment variable
        POSTGRES_USER: "testuser",  // Set username
        POSTGRES_PASSWORD: "testpass" // Set password
      })
      .withExposedPorts(5432) // Explicitly tell Testcontainers to expose port 5432 internally
      .start();

    // Now, get the dynamically mapped port and construct the connection string
    const host = postgresContainer.getHost();
    const port = postgresContainer.getMappedPort(5432); // Get the dynamic host port for 5432

    const connectionString = `postgresql://testuser:testpass@${host}:${port}/testdb`;
    console.log(`Connecting to PostgreSQL at: ${connectionString}`);

    pgClient = new Client({
      connectionString: connectionString,
    });
    await pgClient.connect();
    console.log("Successfully connected to the PostgreSQL container!");

    // Optional: Create a table and insert data to verify
    await pgClient.query("CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(255))");
    await pgClient.query("INSERT INTO users (name) VALUES ('Alice'), ('Bob')");
  }, 30000); // Increase timeout for container startup

  afterAll(async () => {
    if (pgClient) {
      await pgClient.end();
    }
    if (postgresContainer) {
      await postgresContainer.stop(); // Stop and remove the container
    }
  });

  it("should connect to PostgreSQL and have 2 users", async () => {
    const res = await pgClient.query("SELECT COUNT(*) FROM users");
    const userCount = parseInt(res.rows[0].count);
    console.log(`User count: ${userCount}`);
    expect(userCount).toBe(2);
  });

  it("should retrieve a specific user", async () => {
    const res = await pgClient.query("SELECT name FROM users WHERE id = 1");
    expect(res.rows[0].name).toBe("Alice");
  });
});

Explanation for JavaScript/TypeScript:

  1. new GenericContainer("postgres:15.5"): In testcontainers-node, GenericContainer is the primary class for working with most Docker images. We provide the specific image tag "postgres:15.5".
  2. .withEnv({...}): This method takes an object where keys are environment variable names and values are their corresponding strings. This is how we pass POSTGRES_DB, POSTGRES_USER, and POSTGRES_PASSWORD to the PostgreSQL container.
  3. .withExposedPorts(5432): Similar to other languages, this declares that the container’s internal port 5432 should be exposed.
  4. .start(): Initiates the container startup process. It’s an async operation, so we await it.
  5. postgresContainer.getHost(): Retrieves the Docker daemon’s host address, which is typically localhost for local Docker setups.
  6. postgresContainer.getMappedPort(5432): This is crucial. It asks Testcontainers: “For the internal port 5432 I asked you to expose, what random host port did you actually map it to?” This returned port is then used to construct the database connection string.

Mini-Challenge: Customizing a Redis Container

Ready for a small challenge? Your task is to start a Redis container with a specific version, protect it with a password via an environment variable, and then connect to it from your test code using the dynamically mapped port and the password.

Challenge:

  1. Choose your preferred language (Java, Python, or JavaScript/TypeScript).
  2. Create a new test file.
  3. Start a Redis container using the image redis:7.2.4-alpine. (The alpine tag usually means a smaller image size!).
  4. Set a Redis password using the REDIS_PASSWORD environment variable (e.g., mysecretredispassword).
  5. Ensure the default Redis port (6379) is exposed.
  6. Connect to the Redis container using a Redis client library for your chosen language (e.g., Jedis for Java, redis-py for Python, ioredis or node-redis for JS/TS).
  7. Verify the connection by setting and retrieving a simple key-value pair.

Hint: Check the official Redis Docker Hub page for details on configuring Redis with environment variables. For redis:7.2.4-alpine, the standard way to set a password is via the REDIS_PASSWORD environment variable.

What to Observe/Learn:

  • How to find and use specific image versions.
  • How environment variables are container-specific.
  • The pattern for connecting to a password-protected service in a container.
  • Confirming that Testcontainers truly provides a clean, isolated environment for your tests.

(Self-check your solution against the official Testcontainers documentation for Redis container setup if you get stuck!)

Common Pitfalls & Troubleshooting

Even with the best intentions, things can sometimes go awry. Here are a few common issues you might encounter when customizing containers and how to tackle them:

  1. Incorrect Image Name or Tag:

    • Symptom: Testcontainers fails to start, reporting “Image not found” or “no such image.”
    • Cause: A typo in the image name (e.g., postgress instead of postgres) or an invalid tag (e.g., nginx:v1.0 instead of nginx:1.25.3).
    • Fix: Double-check the image name and tag against Docker Hub or the official source. Always prefer specific, stable tags over latest for reproducibility.
      • docker pull <image_name>:<tag> can verify if the image exists and is pullable.

  2. Environment Variable Misspellings or Missing Values:

    • Symptom: The service inside the container doesn’t start correctly, logs indicate configuration errors (e.g., “authentication failed” for a database, or application can’t find a required setting).
    • Cause: You might have misspelled an environment variable name (e.g., POSTGRES_USERNMAE), used the wrong case (variables are often case-sensitive), or forgotten to provide a required variable.
    • Fix: Consult the official Docker image documentation for the service you’re trying to configure. These docs explicitly list the expected environment variables and their purpose. Pay close attention to case sensitivity. You can also inspect the container logs (container.getLogs()) to see startup failures.

  3. Port Collisions (when trying to use fixed host ports):

    • Symptom: Testcontainers fails to start a container, indicating “port already in use” or similar errors.
    • Cause: You’ve attempted to map an internal container port to a specific, fixed host port (e.g., 5432) that is already occupied by another process on your machine (another database instance, another test run, etc.).
    • Fix: Avoid using fixed host ports with Testcontainers. Testcontainers’ dynamic port mapping (where it picks a random available port for you) is its superpower for avoiding such collisions. Rely on methods like container.getMappedPort(internalPort) to retrieve the dynamically assigned port and use that in your client connections. If you absolutely must use a fixed port (rare, and generally a bad practice for test automation), ensure the port is truly free before running tests.

Summary

Fantastic work! You’ve successfully navigated the waters of Testcontainers customization. In this chapter, we covered:

  • Docker Image Selection: How to explicitly specify precise image names and tags (like postgres:15.5) to ensure consistent, reproducible, and accurate test environments.
  • Port Mapping: The crucial role of port mapping in connecting your host machine’s tests to services running inside isolated containers. You learned why Testcontainers favors dynamic port allocation and how to retrieve these randomly assigned host ports.
  • Environment Variables: How to pass configuration settings to your containers using withEnv (or language-specific wrappers) for flexible and dynamic setup, essential for services like databases and message brokers.
  • Practical Application: Hands-on examples in Java, Python, and JavaScript/TypeScript demonstrated how to apply these concepts to a PostgreSQL container, establishing a fully customized and functional test database.
  • Troubleshooting: We discussed common issues like incorrect image names, environment variable errors, and port collisions, along with strategies to resolve them.

You now have the tools to create highly specific and reliable test environments that truly mirror your production setups. This deep level of control is fundamental for building robust integration and end-to-end tests that instill confidence in your application.

In our next chapter, we’ll dive into the fascinating world of container networking and linking, exploring how multiple Testcontainers instances can communicate with each other, simulating complex microservice architectures.

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.