suaveplan/openspec/changes/enterprise-testing-integration/proposal.md

Why

The 2026-04-24 testbed wave shipped seven new packages — @suaveplan/testing-integration and six service-fixture plugins (surrealdb, redis, postgres, mailpit, typesense, garage-s3) — plus four new @suaveplan/testing-e2e modules (console-monitor, network-monitor, multi-session, extension-fixture). All of that work currently lives in docs/superpowers/plans/2026-04-24-*.md and the source tree, but none of it is reflected in openspec/specs/. The 2026-04-25 test-suite audit (docs/superpowers/specs/2026-04-25-test-suite-audit.md) flags this as the single highest-leverage spec-coherence gap — every additional plugin compounds the drift.

This change lifts the already-implemented infrastructure into normative OpenSpec contract. It is a spec-coherence change: code is mostly already in place, but the contract that other genesis packages will rely on (ServiceFixture<TConfig>, TestEnvironment lifecycle, env-bridge inject-key namespace, per-plugin error-code prefixes) must be normative before any consumer integrates against it.

The change also collapses the residual ≥ 95 % coverage gate inside openspec/specs/testing/spec.md into the project-wide 100 % rule that openspec/project.md already mandates, and broadens property-based coverage from "the @suaveplan/testing package itself" to "every pure-function @suaveplan/* package".

What Changes

New capabilities (ADDED)

• testing-integration — ServiceFixture<TConfig> interface, TestEnvironment (topo-sorted parallel-start / reverse-stop with dependsOn), HealthPoller (interval / timeout / AbortSignal), skipIfUnavailable(), createIntegrationSetup() factory + Vitest global-setup bridge, env-bridge passthrough contract, TestEnvironmentOptions.{ clock, rng, signal } propagation, leak/handle assertion on teardown, markFlaky() + quarantine.json, INTEGRATION.<PLUGIN>.* error-code namespace.
• testing-integration-surrealdb — SurrealDB v3 fixture (HTTP /health, random password, env-bridge SURREALDB_URL / SURREALDB_USERNAME / SURREALDB_PASSWORD).
• testing-integration-redis — Redis 7 fixture (TCP PING, REDIS_URL env-bridge with full URL parsing).
• testing-integration-postgres — PostgreSQL 16 fixture (pg_isready in-container exec, configurable db/user/password, POSTGRES_URL).
• testing-integration-mailpit — Mailpit fixture + assertMail() helper (MAILPIT_SMTP_URL / MAILPIT_API_URL, partial-subject + exact-address matching).
• testing-integration-typesense — Typesense 27 fixture (JSON health { ok: true }, random API key, TYPESENSE_URL / TYPESENSE_API_KEY).
• testing-integration-garage-s3 — Garage v2 fixture (dual-port 3900/3902, 7-step init sequence, admin-port health, four env vars).

Modified capabilities

• testing — flatten coverage gate from ≥ 95 % to 100 % on every dimension; broaden the property-based coverage requirement to every pure-function @suaveplan/* package; clarify that the deterministic Clock / Rng / AbortSignal injection contract extends to integration fixtures via TestEnvironmentOptions.
• testing-e2e — add attachConsoleMonitor, attachNetworkMonitor (with assertNoFailures / assertNoMissingAssets / assertNoMixedContent / assertNoCorsErrors), createMultiSessionFixture, extendTestWithExtension, and a default-deny network-sandbox rule.

Capabilities

New Capabilities

• testing-integration (core)
• testing-integration-surrealdb
• testing-integration-redis
• testing-integration-postgres
• testing-integration-mailpit
• testing-integration-typesense
• testing-integration-garage-s3

Modified Capabilities

• testing — coverage gate, property-coverage scope, deterministic-injection cross-cut.
• testing-e2e — console / network / multi-session / extension surface plus network sandbox default.

Impact

• Affected code: packages/testing/testing-integration/**, packages/testing/testing-integration-{surrealdb,redis,postgres,mailpit,typesense,garage-s3}/**, packages/testing/testing-e2e/src/{console-monitor,network-monitor,multi-session,extension-fixture}/** (already shipped; this change is normative-only).
• Affected consumers: every package whose nightly integration suite uses a fixture (today: none on genesis; tomorrow: every db-*, oauth-client, webhook-client, search/cache consumers).
• Inject-key rename: the plans use __integration_failed__; this change codifies it as __suaveplan_integration_failed__ to avoid namespace collisions.
• Plan sweep: every literal 95 % in docs/superpowers/plans/2026-04-24-*.md is replaced with 100 % so plans and specs agree.
• Pre-publish gate: unchanged in shape — bunx turbo lint typecheck test --filter=@suaveplan/<pkg> plus test:coverage at flat 100 % Istanbul thresholds.