How can I bind WireMock’s port 8080 to host port 8081 in Testcontainers when it keeps assigning a random port?

General Discussions
1

Testcontainer cannot configure port binding

A developer using Testcontainers 1.15.2 on Windows 10 wants to map a WireMock container’s default port 8080 to host port 8081.

They use .withCreateContainerCmdModifier() with PortBinding and also call .withExposedPorts(8081), but the container still listens on a random port, causing connection issues from other containers. They are unsure how to correctly configure the container to use the desired host port.

2

This trips up a lot of folks. In Testcontainers, .withExposedPorts() doesn’t fix the host port, it only exposes the container port and then Testcontainers picks a random host port.

If you want the container’s 8080 to map specifically to host 8081, you need to manually set the PortBindings using withCreateContainerCmdModifier(), like this:*

GenericContainer<?> container =
    new GenericContainer<>("wiremock/wiremock:latest")
        .withExposedPorts(8080)
        .withCreateContainerCmdModifier(cmd ->
            cmd.withHostConfig(new HostConfig().withPortBindings(
                new PortBinding(Ports.Binding.bindPort(8081), new ExposedPort(8080))
            ))
        );

container.start();

One more thing, on Windows, if port 8081 is already in use, Docker won’t throw a loud error. Port binding just fails silently and Testcontainers falls back to a random port, which makes debugging confusing.

3

Totally agree with @netra.agarwal . People often assume .withExposedPorts() will bind the host port, but it doesn’t. It only signals to Testcontainers that it should map the container port somehow.

If you really want a fixed host port, withCreateContainerCmdModifier() is the right way. Another option used to be FixedHostPortGenericContainer, but it’s deprecated now in newer Testcontainers versions. So modifying the container command is the recommended approach.

4

Just adding a practical tip: if you don’t care about a fixed port and only need reliable access, it’s usually better to let Testcontainers choose the host port. You can always fetch it at runtime with:

container.getMappedPort(8080)

This avoids host-port conflicts, especially on Windows where Docker Desktop sometimes refuses fixed bindings without clear errors.

So in many setups, the stable pattern is: expose the container port → start container → read the mapped port dynamically.