Test containers: ephemeral host ports by default, so concurrent suites cannot collide

[WilfordGrimley]

Problem

MPCAutofill/cardpicker/tests/conftest.py bound its session-scoped testcontainers to fixed host ports — Postgres 47000, Elasticsearch 9300. A second pytest cardpicker/ on a shared box died at container start with Bind for 0.0.0.0:9300 failed: port is already allocated, which surfaces as thousands of collection ERRORs that read as catastrophic breakage rather than a port clash. Three separate sessions lost real time to it in a single day (one reported "3036 ERRORS" before diagnosing it).

PR #537 made those ports env-overridable (TEST_POSTGRES_PORT / TEST_ELASTICSEARCH_PORT), but nothing assigned distinct values, so the default still collided. Overridability without allocation does not solve concurrency — it just moves the burden onto every session to hand-pick an offset it hopes nobody else has taken.

Fix

Both containers are now started with no host binding at all — their testcontainers constructors already call with_exposed_ports, so Docker assigns a free ephemeral host port per container and the fixtures read back what it actually assigned via get_exposed_port(). Nothing wants a specific port, so nothing can collide: a closed race, not a narrowed window (a random-but-fixed constant would only be the latter).

• New session fixtures postgres_port / elasticsearch_port publish the resolved values.
• django_db_modify_db_settings, ELASTICSEARCH_DSL, settings.ELASTICSEARCH_PORT and pytest-elasticsearch's own elasticsearch_port option all follow them, so nothing is left dialling a stale 9300. The plugin threading moved from pytest_configure (which cannot know an ephemeral port) into the session-scoped elasticsearch fixture; pytest_configure still handles the explicit-override case up front.
• TEST_POSTGRES_PORT / TEST_ELASTICSEARCH_PORT still pin a deterministic port for CI, debugging, or attaching psql/an ES client. Each is independent; setting one re-introduces collision risk for that run, by design.
• Isolation is unchanged — every run still gets its own containers, its own test_* database and its own index.

Tests

test_harness_isolation.py is extended, not relaxed. It now pins the thing that actually closes the race — that the DEFAULT requests no host binding — plus that both overrides are still honoured when set, and that every consumer follows the port Docker really assigned. Port-map keys are normalised to str because testcontainers is unpinned in requirements.txt and 4.14.x (int keys) / 4.15.x (str keys) disagree.

Verification

Two concurrent full-suite runs on one box, both green — the proof that matters for a concurrency bug:

	result	ports Docker assigned
run A	3046 passed, 8 skipped in 303.37s (exit 0)	pg 33260, es 33259
run B	3046 passed, 8 skipped in 301.87s (exit 0)	pg 33261, es 33258

Started within a second of each other, and three unrelated agent pytest sessions were already running on the same box (holding 48511/9931, 47037/9337, 47010/9310 from the old manual-offset workaround) — five concurrent suites, zero bind failures.

Also: test_harness_isolation.py alone 18 passed, 2 skipped (ephemeral default path) and 16 passed, 4 skipped under TEST_POSTGRES_PORT=47654 TEST_ELASTICSEARCH_PORT=9654 (override path). All pre-commit hooks pass (ruff, isort, black, mypy, prettier).

CI is unaffected: test-backend sets neither variable and gets ephemeral ports; nothing in the workflow or the composite action depends on knowing the test-container port.

Docs

• docs/troubleshooting.md — the collision entry is rewritten as FIXED, documenting how ports are now allocated, instead of leaving a workaround for a bug that no longer exists. What is genuinely not fixed (general CPU/memory/connection contention on a shared box, which can still produce OperationalError) is kept and clearly separated from the port issue.
• docs/lessons.md — the "different ports (47000/9300)" aside is corrected; its actual point (testcontainers never touch the prod 5432/9200) is unchanged.

Other fixed-port assumptions found

Swept the harness for the same class of problem. Inside MPCAutofill/, conftest.py was the only place binding a constant host port, and no test asserts a specific port number. Two findings left alone, reported rather than fixed:

1. frontend/playwright.config.ts pins http://localhost:3000 for both baseURL and its webServer — same class of collision for concurrent frontend E2E runs, but out of scope here and not an unambiguous fix (the URL, the dev-server command and CI would all have to move together).
2. A pp_test_pg container on 55432 is running on this box but originates outside this repo (no reference in the tree), so nothing here can address it.

🤖 Generated with Claude Code

https://claude.ai/code/session_013NhYmT1PxCcyemA16dFDxN