## TL;DR

Hardcoded mock-server ports collide the moment you parallelize: two workers grab the same port, or the mock steals the app's port. Fix it with per-worker port allocation: each worker gets its port from its worker index or a small allocator, and a pre-flight check fails fast if the port is taken. No hardcoded ports in test code.

## Error

```text
agent's mock server port conflicted with the app under test: how to isolate
```

Parallel workers failed with address-in-use errors, or the mock server answered requests meant for the real app, producing bizarre test results.

## Steps

1. Find every hardcoded port in the test setup: mock servers, the app under test, and any fixtures. Expected output: a list of fixed ports and who uses each.
2. Replace them with allocated ports: derive the port from the worker index plus a base, or ask the OS for an ephemeral port and pass it to both server and client. Expected output: no fixed ports in test code.
3. Add a pre-flight check: before starting, verify the chosen port is free; fail fast with a clear message if not. Expected output: fast, obvious failures instead of mystery flakes.
4. Scope the app under test the same way: it also gets an allocated port, so mock and app can never collide. Expected output: both sides dynamic, zero overlap.
5. Run the full parallel suite and confirm no address-in-use errors. Expected output: a clean parallel run.

## When to use

- Parallel workers fail with address-in-use errors.
- A mock server intercepts traffic meant for the app under test.
- An agent added a new mock with a hardcoded port that collides.

## When not to use

- Single-process runs: one fixed port is simple and correct.
- The port must be fixed by contract (OAuth redirect URIs, webhook receivers); then serialize those tests instead of parallelizing them.
- The conflict is with something outside the test run (another service on the machine); fix the environment.

## Variant phrasings

### Two mock servers from different suites collided

Same fix: all mocks allocate, none hardcode. The allocator is suite-wide, not per-file.

### Agent hardcoded a new port that collided with the app

Treat hardcoded ports in agent-written test code as a lint error.

### Ephemeral ports and firewall rules

If the environment restricts ports, allocate from an approved range per worker index instead of fully ephemeral.

## Why it happens

Test code starts single-process with a convenient fixed port, and parallelization arrives later. The agent setting up a mock copies the fixed-port pattern because it is the simplest thing that works once. Under parallelism, "works once" becomes "collides always".

## Edge cases

- Clients need to discover the allocated port: pass it via env or a shared config the test reads; never guess.
- Port release timing: a worker that exits uncleanly can hold a port; the pre-flight check plus retry-with-next-port handles it.
- Some CI environments share a host across jobs; include a job-unique offset in the base port.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_wSOR_bdYAzi-c8-JpwVNjA