suaveplan/openspec/changes/enterprise-testing-fixtures-expansion/proposal.md

Why

The genesis monorepo already ships six @suaveplan/testing-integration-* plugin packages (SurrealDB, Redis, Postgres, Mailpit, Typesense, Garage S3) implementing the ServiceFixture<TConfig> interface from @suaveplan/testing-integration. The 2026-04-25 test-suite documentation audit at /mnt/s/web/genesis/docs/superpowers/specs/2026-04-25-test-suite-audit.md (§1, "Coverage gaps in service fixtures") flags the existing plugin set as too narrow for the published package list:

• @suaveplan/oauth-client ships an Authorization Code + PKCE / Client Credentials / OIDC discovery client, but there is no OIDC issuer fixture, so its integration suite cannot exercise a real flow against a real issuer.
• @suaveplan/db-sqlite exists, but no fixture covers MongoDB or MySQL — both are in the standard data-tier surface for downstream apps.
• @suaveplan/garage-s3 is the only object-store fixture; Garage's quirks (admin-port health, layout assignment, custom init sequence) mask AWS-S3 surface differences that show up against MinIO.
• @suaveplan/events plus future stream-processing work has no broker fixture; NATS is the lightest option for a first wave.

Per CLAUDE.md rule 5 ("preserve the full public surface") and rule 2 ("complete all implementations — no stubs"), each of these plugins must be specified normatively before code is written, mirroring the existing six-plugin pattern (image policy, env-bridge, healthcheck, config shape, error-code prefix, injectable fakes, plugin-specific scenarios).

What Changes

This change adds five new capabilities, one per plugin package, using the same shape as the existing testing-integration-* capabilities:

• testing-integration-oidc — Keycloak (preferred) or oauth2-mock-server (lighter alt), exercised by @suaveplan/oauth-client integration tests.
• testing-integration-mongodb — mongo:7.0, with optional replica-set initialisation for transactions/change-streams.
• testing-integration-mysql — mysql:8.4, with charset/collation override and mysqladmin ping health.
• testing-integration-minio — minio/minio with random keys and bucket pre-seeding via the admin API; lives alongside the Garage S3 fixture to expose AWS-S3 surface differences.
• testing-integration-nats — nats:2.10-alpine, optional JetStream + cluster + auth modes, NATS-CLI seeding via injectable execFn.

Each plugin spec mandates:

1. Pinned image with minor tag plus a TODO placeholder for the sha256 digest (preserves the existing six-plugin policy).
2. Env-bridge passthrough — when documented env vars are present and non-empty, no container is started; the fixture returns a config pointing at the live service.
3. Healthcheck — a deterministic readiness probe with a documented default timeout.
4. Config shape — TypeScript interface plus a sibling *.schemas.ts Zod schema reference.
5. Error-code prefix — INTEGRATION.<SERVICE>.* (matching the INTEGRATION.SURREALDB.*, INTEGRATION.GARAGE_S3.* precedent).
6. Injectable fakes — containerFactory, plus per-plugin fetchFn, execFn, or tcpPingFn so unit tests reach 100% Istanbul coverage without Docker.
7. Plugin-specific scenarios — at least three behavioural scenarios per fixture, expressed as WHEN/THEN pairs.

dependsOn?: string[] (the wave-1 ServiceFixture extension flagged by audit §3) is referenced where relevant, e.g. an OIDC-protected app fixture would dependsOn: ['oidc']. The field itself is specified by testing-integration (out of scope for this change); plugins MUST tolerate its presence in TestEnvironmentOptions.

Capabilities

New Capabilities

• testing-integration-oidc
• testing-integration-mongodb
• testing-integration-mysql
• testing-integration-minio
• testing-integration-nats

Modified Capabilities

(none — additive; existing plugin specs are untouched)

Impact

• Affected code: five new packages under packages/testing/testing-integration-<name>/ (implementation in a follow-up plan).
• Affected consumers: none yet on genesis. Once shipped, @suaveplan/oauth-client, @suaveplan/events, future @suaveplan/db-mongodb / db-mysql, and any S3-API consumer become eligible for real-service integration coverage.
• Catalogs: testcontainers already lives in catalog:integration (added by the original six-plugin wave); no new external deps.
• Pre-publish gate: unchanged — bunx turbo lint typecheck test --filter=@suaveplan/testing-integration-<name> plus 100% Istanbul coverage per openspec/AGENTS.md §7.
• Deferred (audit §1, not in this change): Elasticsearch/OpenSearch, Vault, LocalStack, Caddy/nginx reverse-proxy, Kafka, OpenTelemetry collector. Each is a separate future change to keep this proposal scoped.