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

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"