57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
## 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"`
|