Ports and Parallel Workers

## The port is a value you read, not a value you pick A parallel run gives each worker its own stub of the marina berth-booking API, and each stub listens on its own TCP port. Because that number differs per worker — and differs again on the next run — it cannot be written down anywhere in advance. The only correct source is the thing that actually bound it. In mountebank that thing is the `mb` process, and it tells you. This is the half of port handling that teams get wrong more often than allocation itself. Getting mountebank to choose a free port is one line of omission; getting the chosen number all the way into the client that will call `GET /berths` is where suites quietly break. ## Where mountebank puts the number An imposter is created by posting a document to mountebank's control API. If that document omits the `port` field, mountebank binds a free port itself. Two places then carry the answer: - The **response to `POST /imposters`** is the created imposter, and its `port` field holds the number that is now bound. This is the value the worker should use; nothing else is authoritative. - **`GET /imposters`** lists every imposter the running `mb` process currently holds, each with its `port` and `name`. That is the same information after the fact, across every worker, and it is the first thing to look at when something collides. There is a quieter fact worth carrying with it: in mountebank an imposter is addressed *by its port*, so the number you read back is also the identifier you will use later — when you remove it, or when you post further stubs to it. ## Getting it into the code under test Reading the port is half the job. The application under test has to send its marina-berth requests there, which means the number must cross from the harness into the application: 1. Create the imposter and read its `port` from the reply. 2. Compose the base URL from scheme, host and that port. 3. Pass it in as configuration — an environment variable, a start-up property, or a constructor argument on the client the test drives. 4. Start the application or client *after* that, so it resolves an address that exists. Step four is where suites go wrong more often than the read-back itself. An application that resolves its base URL once at boot cannot pick up a port created afterwards, and the resulting failure looks like a connection error rather than an ordering mistake. ## The read-back surface of each product The three products in this space all answer this question, and their answers are easy to attribute to the wrong owner: | product | where the resolved port comes from | what you read | |---|---|---| | Mountebank | mountebank binds it when `port` is omitted | the `port` field of the returned imposter, or `GET /imposters` | | WireMock | `wireMockConfig().dynamicPort()` | `getHttpBaseUrl()`, or `getHttpsBaseUrl()` for TLS | | MockServer | `PortFactory.findFreePort()` supplies a candidate | `getPort()` on `MockServerClient` | The attribution trap here is worth stating plainly, because both halves of it are real identifiers. `PortFactory` is **MockServer's** — `org.mockserver.socket.PortFactory`. WireMock has no such class; its own test suite reaches a free port through `Network.findFreePort()`, and its DSL answer is `dynamicPort()` with the value read back through `getHttpBaseUrl()`. Claiming `PortFactory` for WireMock rather than MockServer is false even though every token in the claim exists somewhere. ## What a hardcoded base URL costs - With one worker it works, which is exactly why it survives review. - With N workers, N minus one of them point at a port they do not own. - If nothing is listening there, the failure is a connection error, which at least names itself. - If **another worker's imposter** is listening there, the request is answered — by the wrong stub set, with a plausible marina-berth body — and the test passes or fails for a reason unrelated to the code. - The symptom moves with worker count, which is why it gets blamed on the runner rather than on the address. ## A short checklist - Does anything in the suite name a port literally, in a fixture, a config file or a container definition? - Does every worker read its own number from its own creation response, not from a shared value? - Does the application receive that number before it resolves its base URL? - If a worker is retried in a fresh process, does it create a new imposter and read the new number?