Set fixed ports to easily debug development services

Part of the magic of Testcontainers libraries is that they dynamically map the container’s ports onto random ports on the host machine to avoid conflicts, ensuring that automated tests run reliably. However, this can make it harder to connect local debugging tools such as an IDE plugin to inspect a datastore, or k9s to manage a Kubernetes cluster.

You can now configure Testcontainers Desktop to also proxy these random ports to a fixed port on your machine, available to debug Testcontainers services. To do so, simply click "open config location" in the "Services" sub-menu. You can then clone the sample configuration file and rename it to my-service.toml, where "my-service" is whatever your service is actually called, and finally pick a fixed port that should always be available to debug the service. Once you save the file, it's detected and reloaded automatically.

For example, here we've defined a service called redis-cache and therefore the file is called redis-cache.toml. We've configured the service to always be available at port 6379, and to match any container started from the redis image.

In the Java example below we spin up a redis container, write to it, then test that we can read the value. The test relies on a dynamically mapped port, and therefore port 6379 wouldn't usually be available on the host machine (i.e. your laptop).

@Test
public void canWriteAndReadFromRedisCache() {
    try (
        GenericContainer<?> container = new GenericContainer<>(DockerImageName.parse("redis:6.0.5"))
                // this port is exposed from the perspective of the container.
                .withExposedPorts(6379);) {
        container.start();

        // The test remains reliable as it relies on a dynamically mapped port
        int mappedPort = container.getFirstMappedPort();
        Jedis jedis = new Jedis(container.getHost(), mappedPort);
        jedis.set("foo", "bar");
        String value = jedis.get("foo");

        // Set a breakpoint here to connect to the database 
        // When the test completes, the container is cleaned up automatically
        assertThat(value)
                .as("Redis key foo equals bar")
                .isEqualTo("bar");
    }
}

Thanks to Testcontainers Desktop, the redis service is now exposed on port 6379 as per our configuration above. We can test that this works by connecting our IDE plugin for redis and checking that it contains the k/v "foo: bar" as expected.

Updated on August 3, 2023 to reflect the simplified format of the TOML file.