Initial Commit

openspec/changes/enterprise-testing-integration/specs/testing-integration-postgres/spec.md

@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: PostgreSQL 16 image policy
+
+The `@suaveplan/testing-integration-postgres` plugin SHALL pin to `postgres:16` (name + major version). A follow-up operational change tracked at `docs/superpowers/specs/2026-04-25-test-suite-audit.md §5` will pin to `sha256:<digest>`.
+
+#### Scenario: Image tag pinned
+
+- **WHEN** the container factory is invoked without injection
+- **THEN** the resulting container uses image `postgres:16`
+
+### Requirement: Env-bridge contract
+
+The plugin SHALL declare and forward the environment variable `POSTGRES_URL`. When `POSTGRES_URL` is set on the parent process at construction time, the fixture MUST enter env-bridge passthrough mode.
+
+#### Scenario: env() returns POSTGRES_URL
+
+- **WHEN** the fixture has started
+- **THEN** `fixture.env()` returns `{ POSTGRES_URL: "postgres://…" }`
+
+#### Scenario: Passthrough mode skips container
+
+- **WHEN** `POSTGRES_URL` is set at construction
+- **THEN** `start()` does not invoke the container factory AND `stop()` is a no-op
+
+### Requirement: Configurable database / user / password
+
+The fixture options SHALL accept `database?: string; user?: string; password?: string`. Defaults MUST be `database = "test"`, `user = "test"`, `password` randomly generated per run with at least 32 bytes of entropy. The container's `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` env vars MUST be set from these values.
+
+#### Scenario: Defaults applied
+
+- **WHEN** the fixture is constructed without options
+- **THEN** `config.database === "test"` AND `config.user === "test"` AND `config.password` is a non-empty random string
+
+### Requirement: Healthcheck contract — pg_isready
+
+`isHealthy()` SHALL execute `pg_isready -U <user> -d <database>` **inside** the Postgres container via testcontainers' `exec` API. The fixture constructor SHALL accept an optional `execFn` that defaults to the container's exec method and MAY be substituted for tests. A 0 exit code means healthy; any other exit code resolves to `false`.
+
+#### Scenario: pg_isready exit 0 is healthy
+
+- **WHEN** `pg_isready` exits with code 0
+- **THEN** `isHealthy()` resolves `true`
+
+#### Scenario: Non-zero exit is unhealthy without throwing
+
+- **WHEN** `pg_isready` exits with code 2
+- **THEN** `isHealthy()` resolves `false` and does not throw
+
+### Requirement: Error-code prefix
+
+Errors thrown from the plugin SHALL carry codes matching `^INTEGRATION\.POSTGRES\.[A-Z_]+$` (e.g. `INTEGRATION.POSTGRES.START_FAILED`, `INTEGRATION.POSTGRES.EXEC_FAILED`).
+
+#### Scenario: Coded exec failure
+
+- **WHEN** the injected `execFn` throws
+- **THEN** `isHealthy()` resolves `false` AND the OTel error counter records `code = "INTEGRATION.POSTGRES.EXEC_FAILED"`