# Capability Spec Delta: testing-integration-surrealdb (testing-integration-spec-and-generics-hardening) **Package**: `@suaveplan/testing-integration-surrealdb` **Status**: PROPOSED ## ADDED Requirements ### Requirement: SurrealDBFixture implements ServiceFixture The package SHALL export `SurrealDBFixture` with `name === "surrealdb"`. `SurrealDBConfig` SHALL be `{ url: string; namespace: string; database: string; username: string; password: string }`. #### Scenario: name property is "surrealdb" - **WHEN** an instance's `.name` is read - **THEN** the value is the literal `"surrealdb"` **Verified by:** `src/fixture/surrealdb-fixture.test.ts::"name property returns surrealdb"` --- ### Requirement: Env-bridge passthrough mode (3 vars) When `SURREALDB_URL`, `SURREALDB_USERNAME`, AND `SURREALDB_PASSWORD` are all set and non-empty, `start()` MUST return the config directly without starting a container. Namespace/database fall back to `SURREALDB_DEFAULT_NAMESPACE`/`SURREALDB_DEFAULT_DATABASE` unless overridden via options. In passthrough mode `stop()` MUST be a no-op and `healthCheck()` MUST return `false` (no container to probe). #### Scenario: returns config from env vars - **WHEN** all three env vars are set - **THEN** `start()` returns the config without invoking testcontainers #### Scenario: stop is a no-op in passthrough mode - **WHEN** the fixture started in passthrough mode and `stop()` is called - **THEN** no container is touched #### Scenario: healthCheck returns false in passthrough mode - **WHEN** `healthCheck()` is called after a passthrough start - **THEN** the result is `false` **Verified by:** `src/fixture/surrealdb-fixture.test.ts::"passthrough mode: returns config from env vars"` AND `src/fixture/surrealdb-fixture.test.ts::"passthrough mode: stop is a no-op"` AND `src/fixture/surrealdb-fixture.test.ts::"passthrough mode: healthCheck returns false when no container"` --- ### Requirement: Container mode When env vars are partially or unset, `start()` MUST start a SurrealDB v3 container via the injected `containerFactory` (or `GenericContainer`), pass `start --auth --user --pass ` as the command, expose `SURREALDB_CONTAINER_PORT`, and return `{ url: "ws://localhost:", namespace, database, username: SURREALDB_DEFAULT_USERNAME, password: }`. Image MUST be overridable. Namespace/database MUST be overridable via constructor options. #### Scenario: container mode happy path returns correct config - **WHEN** `start()` completes container boot - **THEN** `result.url`, `namespace`, `database`, `username`, `password` are populated #### Scenario: stop calls container.stop() - **WHEN** `stop()` follows `start()` in container mode - **THEN** the container's `stop()` is invoked exactly once #### Scenario: image override: factory called with custom image - **WHEN** the fixture is constructed with `image: "x"` - **THEN** the container factory is invoked with `"x"` #### Scenario: namespace and database overrides reflected in config - **WHEN** the fixture is constructed with custom namespace/database - **THEN** the returned config uses those overrides #### Scenario: factory falls back to dynamic GenericContainer import - **WHEN** no `containerFactory` is injected - **THEN** the fixture dynamically imports testcontainers and uses `GenericContainer` #### Scenario: start() stops container if getMappedPort throws - **WHEN** `getMappedPort()` throws after the container has booted - **THEN** `start()` calls `container.stop()` and clears the reference before re-throwing **Verified by:** `src/fixture/surrealdb-fixture.test.ts::"container mode happy path: returns correct config"` AND `src/fixture/surrealdb-fixture.test.ts::"container mode: stop calls container.stop()"` AND `src/fixture/surrealdb-fixture.test.ts::"image override: factory called with custom image"` AND `src/fixture/surrealdb-fixture.test.ts::"namespace and database overrides reflected in config"` AND `src/fixture/surrealdb-fixture.test.ts::"resolveContainerFactory: returns factory from dynamic import when no containerFactory"` AND `src/fixture/surrealdb-fixture.test.ts::"start(): stops container and clears reference when getMappedPort throws"` --- ### Requirement: HTTP /health probe In container mode, `healthCheck()` MUST `GET http://localhost:/health` via the injected `fetchFn` (default `globalThis.fetch`) and return `res.ok`. Network errors MUST be swallowed and return `false`. Without a started container, `healthCheck()` MUST return `false`. #### Scenario: returns true when fetchFn returns ok - **WHEN** the injected fetch returns `{ ok: true }` - **THEN** `healthCheck()` resolves to `true` #### Scenario: returns false when fetchFn throws - **WHEN** the injected fetch throws - **THEN** `healthCheck()` resolves to `false` #### Scenario: returns false when no container - **WHEN** `healthCheck()` is called before `start()` - **THEN** the result is `false` **Verified by:** `src/fixture/surrealdb-fixture.test.ts::"container mode: healthCheck returns true when fetchFn returns ok"` AND `src/fixture/surrealdb-fixture.test.ts::"container mode: healthCheck returns false when fetchFn throws"` AND `src/fixture/surrealdb-fixture.test.ts::"healthCheck returns false when no container"` --- ### Requirement: Random per-run password In container mode, `start()` MUST generate the SurrealDB root password via `crypto.randomUUID()` and use it as both the container start arg and the returned config field. Password reuse across runs MUST NOT occur. #### Scenario: generated password matches UUID format - **WHEN** `start()` runs in container mode - **THEN** `result.password` matches the UUID v4 regex **Verified by:** `src/fixture/surrealdb-fixture.test.ts::"generated password matches UUID format"` --- ### Requirement: stop() is idempotent `stop()` MUST be safe to call when no container has been started. #### Scenario: stop without start is a no-op - **WHEN** `stop()` is called on a freshly-constructed fixture - **THEN** no error is thrown **Verified by:** `src/fixture/surrealdb-fixture.test.ts::"stop when no container is a no-op"` --- ### Requirement: testing-integration is a peer dependency The package's `package.json` MUST list `@suaveplan/testing-integration` and `testcontainers` in `peerDependencies`, NOT in `dependencies`. #### Scenario: variant does not bundle the core or testcontainers - **WHEN** the published `package.json` is inspected - **THEN** `dependencies` does not contain either symbol **Verified by:** `src/fixture/surrealdb-fixture.test.ts::"name property returns surrealdb"`