Initial Commit

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

@@ -0,0 +1,65 @@
+## 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"`