In Testcontainers, what do GenericContainer's withExposedPorts, withEnv and withCommand actually do?

## GenericContainer is a builder for a create request `GenericContainer` is Testcontainers' base class for running an arbitrary Docker image from a test. You construct it with an image reference and then chain `with…` methods on it. Every one of those methods mutates the *specification* that Testcontainers will send to the Docker daemon when you call `start()`; each returns the container object itself so the calls chain. Nothing contacts Docker until `start()` runs. That single fact explains most of the behaviour candidates get wrong. Configuration is create-time. A container that is already running has already been created from a spec, and mutating the Java object afterwards has no effect on it. ## withExposedPorts `withExposedPorts(Integer... ports)` names ports *inside* the container — the port the server process actually binds, such as 6379 for Redis or 8080 for an HTTP service. Testcontainers then asks Docker to publish each of them on an ephemeral free port on the host. The deliberate design choice here is that you do not pick the host port. Fixed host ports are the classic source of flaky suites: two tests running in parallel collide, or the developer already has the same service running locally, and the failure looks like a mysterious connection or authentication error rather than a port clash. By letting the OS pick, Testcontainers makes concurrent runs safe. The price is that your test must ask the container which host port it got rather than assuming one. Note what `withExposedPorts` does *not* do: it does not make a process listen on that port. If the image's server binds only to a different port, or binds to loopback inside the container, publishing the port will not help. ## withEnv `withEnv(String key, String value)` sets an environment variable inside the container, exactly as `-e KEY=value` would on the command line. This is the primary configuration channel for nearly every official image — database images read credentials and database names from environment variables, application images read their profile or log level. There is also a map-taking overload for setting several at once. Because environment variables are read by the image's entrypoint at startup, they are meaningless after the container is running — another reason configuration is a create-time concern. ## withCommand `withCommand(String... command)` overrides the image's default command. It is the equivalent of appending arguments after the image name in `docker run`. Use it to pass flags to a server (`redis-server --appendonly yes`), to run the image in a different mode, or to keep a short-lived image alive for the duration of a test. It replaces the command, not the entrypoint: if the image defines an entrypoint script, your arguments are passed to that script rather than executed directly, which surprises people when they pass a shell pipeline. When you genuinely need shell semantics, run a shell explicitly, e.g. `withCommand("sh", "-c", "…")`. ## The rest of the fluent surface The same builder carries the other create-time concerns: labels, network membership and aliases, the readiness check, the startup timeout, a log consumer, and file copies into the container. They all follow the same rule — set them before `start()`. ## start(), and what happens then `start()` is the moment everything becomes real: Testcontainers pulls the image if it is not present locally, creates the container from the accumulated spec, starts it, and blocks until the configured readiness check passes before returning. Only after `start()` returns do the runtime accessors make sense, because only then does a mapped host port exist. Calling an accessor that depends on runtime state before `start()` fails rather than returning a placeholder. ## Common mistakes The frequent ones are: expecting `withExposedPorts(5432)` to give you host port 5432; configuring after `start()` and wondering why nothing changed; passing a whole shell command line as a single string to `withCommand` and being confused when the image treats it as one argument; and assuming an environment variable is honoured by an image that does not read it — the variable is set faithfully, the image simply ignores it. ## Interview framing A junior is expected to reach for `GenericContainer` for an image with no dedicated module and to configure it correctly. Saying "these are create-time settings, and the host port is random on purpose" covers both the mechanics and the reasoning behind the API in one sentence.