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

Not specified by the original author.

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

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/pstwSORbdYAzi-c8-JpwVNjA

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

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

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.