suaveplan/openspec/archive/2026-05-02-surrealdb-integration-tests/proposal.md

Why

We have a complete real-services test harness (docker/docker-compose.test.yml + the seven @suaveplan/testing-integration-* fixtures) and zero consumers wired to it. grep -rln "testing-integration-" packages apps outside packages/dev/testing-integration* returns nothing. Meanwhile @suaveplan/database/surrealdb ships its adapter tests against an in-suite makeFakeClient() DI fake (src/adapter/surreal-adapter.test.ts). That fake validates the adapter's shape against the SurrealClientLike port; it does not verify that the real surrealdb.js v2 client + SurrealDB v3.0.4 server actually behave the way the adapter assumes.

The db.create() drops content in surrealdb.js v2 + SurrealDB v3 issue we already burned on (forced the workaround INSERT INTO query) is exactly the class of bug a fake client cannot catch. Adapter assumptions about session use-NS/DB binding, query parameter passthrough, transaction semantics, version detection, and singleton lifecycle all need to be exercised against the real engine — that is the whole point of the docker-compose stack.

This change wires @suaveplan/database/surrealdb to @suaveplan/testing-integration-surrealdb as the first real consumer of the integration harness, establishing the pattern the remaining I/O packages will follow (db-sqlite against postgres, storage-s3 against garage, email-* against mailpit, search-* against typesense, etc.). Scope is intentionally narrow: surrealdb only, no sweep yet.

What Changes

New integration-test surface in @suaveplan/database/surrealdb

• New tests/integration/ directory (sibling of tests/), separated from the unit suite. Per the project's hybrid placement rule (per-feature unit tests co-located in src/; cross-cutting tests in tests/), real-DB tests live in tests/integration/ because they are cross-cutting (depend on a backing service rather than a single feature module).
• New vitest.integration.config.ts extending the package's existing config, registering SurrealDBFixture via createIntegrationSetup({ surrealdb: new SurrealDBFixture() }).
• New script entry in package.json: "test:integration": "vitest run --config vitest.integration.config.ts".
• Default unit suite (bunx turbo test --filter=@suaveplan/database/surrealdb) does not run integration tests — they are opt-in via the new script and CI gate.
• Each integration test calls skipIfUnavailable("surrealdb", inject) at the top so the suite is skipped (not failed) when docker is not running locally.

Integration test coverage (real SurrealDB v3.0.4 container)

• surreal-adapter.integration.test.ts — connect / use(ns,db) / signin / query SELECT 1 / disconnect, asserting against the live engine, not a fake.
• singleton.integration.test.ts — getSingleton returns the same connected adapter instance for the same name, closeSingleton actually closes the WS, closeAllSingletons is reverse-order safe, registry isolation when an explicit Map is passed.
• version-detector.integration.test.ts — version detector returns the real server version string and parses it correctly.
• init.integration.test.ts — namespace + database creation flow against the live engine, including the db.create() drop-content workaround path documented in feedback memory surrealdb-create-content-drop.
• connection.integration.test.ts — 'ConnectionRefused' error code surfacing matches the documented branch (error?.code === 'ConnectionRefused' || error?.message?.includes('Unable to connect')).
• discovery.integration.test.ts — schema discovery against a real fresh database with seeded tables/fields.

CI gate

• New turbo task test:integration that runs only on the integration entry script. Wired in CI behind docker compose -f docker/docker-compose.test.yml up -d + the env-bridge variables from docker/README.md.
• Unit-coverage gate (test:coverage) is unchanged — integration tests do not count toward Istanbul 100% on src/. They verify behaviour against real I/O, which is orthogonal to source coverage.

Out of scope

• Sweeping the same pattern across the other six fixtures (postgres, redis, mailpit, typesense, garage-s3, step-ca). That follows in separate per-package changes after surrealdb proves the wiring.
• Replacing the existing makeFakeClient() adapter unit tests. The fake-client suite stays — it pins the port contract and runs in milliseconds without docker. Integration tests are additive.
• Changes to @suaveplan/testing-integration-surrealdb itself. The fixture is already shipped and conformant.
• Changes to the docker-compose stack itself.

Capabilities

New Capabilities

• database-surrealdb-integration — defines the integration-test contract for @suaveplan/database/surrealdb: which adapter behaviours MUST be verified against a real container, the env-bridge passthrough rule, the local-skip rule when docker is unavailable, and the CI gate.

Modified Capabilities

• None. testing-integration-surrealdb is consumed unmodified.

Dependencies

This change is the consumer wire-up; it depends on three upstream fixes landing first:

1. testing-integration-vite-entry-fix — without it, @suaveplan/testing-integration-surrealdb cannot be imported by name (its dist/index.js is not emitted).
2. testing-integration-build-fix (Option A) — without it, createIntegrationSetup() returns a data:video/mp2t;base64,… URL for globalSetup, which Vitest cannot load. surrealdb-integration-tests consumes the public createIntegrationSetup API and would otherwise have to hand-roll a TestEnvironment driver (the rebel pattern in storage-s3 that this stack eliminates).
3. testing-integration-bun-runtime-compat (Option B) — without it, bunx vitest run panics in uv_version_string before any container starts; this monorepo runs every test under Bun per CLAUDE.md.

surrealdb-integration-tests MUST NOT be archived until all three upstream changes have shipped and the suite has been observed actually starting a real SurrealDB container under Bun.

Impact

• Affected code: packages/database/surrealdb/tests/integration/** (new), packages/database/surrealdb/vitest.integration.config.ts (new), packages/database/surrealdb/package.json (new script + dev dep on @suaveplan/testing-integration-surrealdb and @suaveplan/testing-integration).
• Affected consumers: none — this is additive test coverage on a leaf package.
• CI: new job step that brings up docker-compose.test.yml and runs bunx turbo test:integration --filter=@suaveplan/database/surrealdb. Local developers can either run docker first or rely on skipIfUnavailable() to no-op the suite.
• Documentation: README of @suaveplan/database/surrealdb gets a new "Integration tests" section. docker/README.md already covers the env-bridge — no change needed there.
• CLAUDE.md / MANIFEST.md: no new package, so no manifest regeneration. The surrealdb package description in CLAUDE.md does not need to change.