conformance-suite

(no submodules)

Purpose

Provides runConformanceSuite, a driver-agnostic test factory that accepts a DriverFactory callback and executes a standard suite of CRUD, transaction, and rollback assertions against any SQLite driver. Running the same suite against both the Bun driver and a WASM driver ensures that both runtimes satisfy the same behavioural contract, catching driver-specific regressions before they reach production.

The suite is intentionally minimal — it tests the lowest-level SQL operations that the adapter layer depends on. Higher-level tests (prepared-statement cache behaviour, migration runner idempotency, OTel counter increments) live in their respective unit test files.

Features

runConformanceSuite(name, factory) — registers a Vitest describe block named ${name} conformance
Tests: table creation, SELECT, INSERT with parameters, transaction commit, transaction rollback, UPDATE, DELETE
DriverFactory interface — a single create() method returning { sqlite, close }
Runs under the Bun driver via bun-conformance.test.ts

Usage: Basic Example

import { runConformanceSuite } from "@suaveplan/db-sqlite/src/conformance/conformance-suite";
import { createBunDriver } from "@suaveplan/db-sqlite/drivers/bun-driver";

runConformanceSuite("Bun driver", {
  async create() {
    return createBunDriver({ filename: ":memory:" });
  },
});

Usage: Advanced Example

import { runConformanceSuite } from "@suaveplan/db-sqlite/src/conformance/conformance-suite";

// Custom driver shim for testing
runConformanceSuite("Custom driver", {
  async create() {
    const driver = await MyCustomDriver.open(":memory:");
    return { sqlite: driver.raw, close: async () => driver.close() };
  },
});

API Reference

`DriverFactory`

interface DriverFactory {
  create(): Promise<{ sqlite: any; close: () => Promise<void> }>;
}

`runConformanceSuite(name: string, factory: DriverFactory): void`

Registers a Vitest describe block with 5 test cases covering the core SQLite contract.

Implementation Notes

The conformance suite uses raw sqlite.run() / sqlite.query().all() calls rather than going through SqliteAdapter or Drizzle. This keeps the suite focused on driver-level semantics rather than adapter-layer concerns, making it useful for validating new driver implementations independently of the adapter code.

Each test creates fresh tables with unique names to avoid interference between tests within the same suite run.

2.5 KiB Raw Blame History