Parallel + container-backed test infra: paratest + testcontainers-php

[tonydspaniard]

Motivation

Two gaps in the current testing story:

1. Ext/DB-backed tests are CI-only. Tests that need ext-mongodb, ext-redis, ext-memcached, Beanstalk (pda/pheanstalk), or a live database for the Cycle ORM bridge (univeros/persistence) cannot run on a typical dev machine without those extensions/services installed, so they only really execute in CI. That makes a whole class of integration code slow to iterate on and easy to break locally without noticing (e.g. the MongoSessionHandlerTest tearDown() quirk).
2. Suite wall-clock grows. As packages land (the suite is already 200+ tests across 28 packages) a single-process PHPUnit run gets slower, especially once container-backed integration tests are added.

These two tools are complementary and address both:

• testcontainers-php — spin up throwaway Docker containers (Mongo, Redis, Memcached, Beanstalk, MySQL/Postgres) per test run, so the ext/DB integration tests run identically locally and in CI, with no global service install.
• paratest — parallelize the PHPUnit 11 suite to keep it fast as it grows.

Proposed scope

• Add brianium/paratest (dev) and wire a composer test:par script alongside the existing composer test. Confirm it cooperates with the Altair\TestReporter PHPUnit extension (JSON report) and coverage.
• Add a testcontainers-php dev dependency and a small base TestCase/trait that lazily boots the container a given integration test needs, skipping gracefully when Docker is unavailable (so composer test without Docker still works, like today).
• Port the currently CI-only ext/DB tests to container-backed fixtures: Session (Mongo/Predis/PDO handlers), Cache (Redis/Memcached/Predis storage), Persistence (Cycle against a real DB), Messaging (Beanstalk transport).
• Decide isolation strategy for parallel + shared containers (see risks) and document it.
• Update CI (.github/workflows/ci.yml) to use the container-backed path and (optionally) paratest, removing the bespoke service setup.
• Docs: a short "running the integration suite" section.

Risks / open questions

• Isolation under parallelism is the crux. paratest runs N worker processes; if they share one Redis/DB container they will contaminate each other. Options: a container instance per worker (TEST_TOKEN-keyed), or one container with per-test isolation (unique DB name / Redis keyspace / Mongo database per test). Needs a decision before porting tests.
• Docker becomes a dev/CI prerequisite for the integration suite. The unit suite must stay Docker-free and fast (graceful skip when Docker is absent).
• Coverage + paratest + the TestReporter extension interaction needs verifying (merging per-process coverage; the golden-file determinism of build/test-results.json).
• Container boot time vs. CI minutes — measure before/after.

Related

• Pairs naturally with univeros/doctor's database_reachable / extensions_loaded checks — a container-backed dev loop makes those probes pass locally instead of skipping.
• Separate initiative from the introspection/suggest tooling; this is purely test infrastructure.

[tonydspaniard]

PR #208 (merged) landed the foundation + first proof:

• brianium/paratest (dev) + composer test:par for parallel local runs; single-process composer test stays the canonical gate / CI runner.
• A dependency-free docker-CLI integration harness (tests/Support/Integration/DockerContainer.php) — testcontainers-php was rejected because its Docker client needs psr/http-message ^2, which conflicts with relay/relay ~1.0 + neomerx/cors-psr7 ^1.0 (documented in AGENT.md §6).
• PredisCacheItemStorageTest ported via RedisServer (env → existing 6379 service → booted redis:7-alpine → skip). Runs locally with Docker and no PHP extension; reuses the CI service unchanged.
• Docs: AGENT.md §6 "Running the integration suite" + parallel-safety status.

Still open

• Per-test / per-worker isolation for parallel-safety (the crux). Known offenders today: tests/Cache/tmp shared by the filesystem-cache tests, and the events log in Events\ReaderTest — they collide under test:par. Strategy to implement: per-worker container / per-test keyspace, DB name, or temp dir keyed off TEST_TOKEN.
• Port the remaining services: Beanstalk (pheanstalk, pure-PHP → extension-free) and Cycle-over-PDO are the next extension-free wins; ext--bound Mongo/Memcached/Redis still need their client extension even with a container.
• Switch CI to the container path and (optionally) paratest; measure boot time vs CI minutes.
• Verify coverage merging under paratest.

[tonydspaniard]

Re: the testcontainers-php rejection — it's unblockable, but only via a dependency migration now tracked in #209:

• relay/relay 3.0 already allows psr/http-message ~1.0 || ~2.0 (relax Milestone tasks univeros components version 1.0.0 #1), but
• neomerx/cors-psr7 (latest 3.0.2) still pins psr/http-message ^1.0 and has no PSR-7-v2 release — so the CORS middleware must be replaced/forked before psr/http-message ^2 can resolve, which is the prerequisite for testcontainers-php's Docker client.

Until #209 lands that chain, the dependency-free docker-CLI helper (PR #208) stays the right call. Revisit testcontainers-php once PSR-7 v2 is in.

(Also: the composer test:par parallel runner is pinned to paratest 7.8.5 by PHPUnit 11; paratest 7.22 needs PHPUnit 13 — also tracked in #209.)