55 lines
4.7 KiB
Markdown
55 lines
4.7 KiB
Markdown
## 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.
|