Initial Commit

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

@@ -0,0 +1,49 @@
+## 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.