66 lines
3.1 KiB
Markdown
66 lines
3.1 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: SurrealDB v3 image policy
|
|
|
|
The `@suaveplan/testing-integration-surrealdb` plugin SHALL pin to `surrealdb/surrealdb:v3.0.4` (name + minor version). A follow-up operational change tracked at `docs/superpowers/specs/2026-04-25-test-suite-audit.md §5` will pin to `sha256:<digest>`; that pinning is **out of scope** for this change.
|
|
|
|
#### Scenario: Image tag pinned
|
|
|
|
- **WHEN** the fixture's container factory is invoked without injection
|
|
- **THEN** the resulting `GenericContainer` is constructed with image `surrealdb/surrealdb:v3.0.4`
|
|
|
|
### Requirement: Env-bridge contract
|
|
|
|
The plugin SHALL declare and forward the following environment variables: `SURREALDB_URL`, `SURREALDB_USERNAME`, `SURREALDB_PASSWORD`. When all three are set on the parent process at construction time, the fixture MUST enter env-bridge passthrough mode and skip container start.
|
|
|
|
#### Scenario: env() returns the full set
|
|
|
|
- **WHEN** the fixture has started in container mode
|
|
- **THEN** `fixture.env()` returns a record whose keys are exactly `SURREALDB_URL`, `SURREALDB_USERNAME`, `SURREALDB_PASSWORD`
|
|
|
|
#### Scenario: Env-bridge passthrough
|
|
|
|
- **WHEN** all three env vars are set on `process.env` at construction
|
|
- **THEN** `start()` does not invoke the container factory AND `stop()` is a no-op
|
|
|
|
### Requirement: Healthcheck contract
|
|
|
|
`isHealthy()` SHALL issue an HTTP `GET /health` request to the SurrealDB endpoint. A 2xx response means healthy. Connection errors AND non-2xx responses MUST resolve to `false`, never throw.
|
|
|
|
#### Scenario: 2xx is healthy
|
|
|
|
- **WHEN** `/health` returns 200
|
|
- **THEN** `isHealthy()` resolves `true`
|
|
|
|
#### Scenario: Connection refused does not throw
|
|
|
|
- **WHEN** the endpoint refuses the connection
|
|
- **THEN** `isHealthy()` resolves `false` and does not throw
|
|
|
|
### Requirement: Random password per run
|
|
|
|
In container mode the fixture SHALL generate a fresh random password per `start()` call. The password MUST be at least 32 bytes of entropy, rendered as URL-safe base64 or hex.
|
|
|
|
#### Scenario: Two independent fixtures generate different passwords
|
|
|
|
- **WHEN** two fixtures start in the same process
|
|
- **THEN** their `config.password` values differ
|
|
|
|
### Requirement: Injectable factories
|
|
|
|
The fixture constructor SHALL accept optional `containerFactory` and `fetch` parameters. The defaults invoke `testcontainers` and the global `fetch`. Test-of-test code MAY substitute these to drive deterministic behaviour.
|
|
|
|
#### Scenario: Injected fetch drives health probe
|
|
|
|
- **WHEN** `fetch` is replaced with a stub that always returns a 503
|
|
- **THEN** `isHealthy()` resolves `false`
|
|
|
|
### Requirement: Error-code prefix
|
|
|
|
Errors thrown from the plugin SHALL carry codes matching `^INTEGRATION\.SURREALDB\.[A-Z_]+$` (e.g. `INTEGRATION.SURREALDB.START_FAILED`, `INTEGRATION.SURREALDB.STOP_FAILED`). Cross-cutting codes (`INTEGRATION.HEALTH_TIMEOUT`, `INTEGRATION.ABORTED`) are inherited from `@suaveplan/testing-integration`.
|
|
|
|
#### Scenario: Coded error on start failure
|
|
|
|
- **WHEN** the container fails to bind a port
|
|
- **THEN** `start()` rejects with a structured error whose `code === "INTEGRATION.SURREALDB.START_FAILED"`
|