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

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"