testkit
Contract conformance test kit: a plugin database binding that behaves like the one a deployed host grants.
A plain in-memory fake accepts anything. On a host, env.DB reaches an
isolated unit through the adapter the operator deployed: SQL is scoped to
the plugin's own tables, every batch is one transaction held to the
adapter's advertised caps, and a result past a cap is a typed
limit_exceeded error. createTestDatabase gives a Vitest or
node:test suite that same binding, backed by the bookclerk-db-testkit
binary from the Bookclerk workspace under one of three capability
profiles:
first-party: the shipped sqlite and Postgres adapters (256 KiB results, streamed reads).d1: the D1 adapter (smaller payload and statement limits).minimum: the smallest advertisement a host connects to (4,096-byte results, 1,024-byte cells, one row per statement, no streamed reads).
Run plugin database code under all three (TEST_DATABASE_PROFILES): what works on the shipped adapters has to work when an adapter advertises only the minimums.
import { createTestDatabase, TEST_DATABASE_PROFILES } from "@bookclerk/plugin-sdk/testkit";
for (const profile of TEST_DATABASE_PROFILES) {
const db = await createTestDatabase({ profile, migrations: MIGRATIONS });
try {
await db.binding.prepare("INSERT INTO notes (id, body) VALUES (?, ?)").bind(1, "hi").run();
const { results } = await db.binding.prepare("SELECT body FROM notes").all();
} finally {
await db.close();
}
}
The binary is found through the BOOKCLERK_DB_TESTKIT environment
variable or options.binary, else as bookclerk-db-testkit on PATH
(cargo build -p bookclerk-db-testkit in the workspace builds it).
bookclerk-plugin test (cargo plugin -- test <dir> in the workspace)
runs a plugin's suite once per profile, setting both that variable and
BOOKCLERK_DB_TESTKIT_PROFILE, which is the default profile. This
module runs under Node, not inside an isolate.
A served test binding and the process behind it.
readonly binding: DatabaseBinding;
The D1-shaped binding, as env.<BINDING> on a host.
readonly profile: "first-party" | "d1" | "minimum";
The profile being enforced.
close(): Promise<void>;
Stops the kit process; the in-memory unit goes with it.
Promise<void>
Once the process has exited.
limits(): Promise<DbCapabilities>;
The profile's advertisement: the caps every batch is held to.
Promise<DbCapabilities>
The capability advertisement, as binding.limits() reports it.
Options for createTestDatabase.
binary?: string;
Path of the bookclerk-db-testkit binary; see the module docs for the default.
migrations?: PluginMigration[];
The plugin's databaseMigrations registration, applied before the
binding is handed out the way the host applies it at enrollment.
profile?: "first-party" | "d1" | "minimum";
Capability profile to enforce. Defaults to BOOKCLERK_DB_TESTKIT_PROFILE
when bookclerk-plugin test sets it, else minimum, the strictest.
type TestDatabaseProfile = typeof TEST_DATABASE_PROFILES[number];
One of TEST_DATABASE_PROFILES.
const TEST_DATABASE_PROFILES: readonly ["first-party", "d1", "minimum"];
The capability profiles the kit enforces, in the order conformance runs report them.
function createTestDatabase(options?): Promise<TestDatabase>;
Spawns the kit under options.profile with options.migrations applied
and returns the served binding.
| Parameter | Type | Description |
|---|---|---|
options? |
TestDatabaseOptions |
Profile, registration and binary location. |
Promise<TestDatabase>
The binding and its process; call close() when the test ends.
Error when the binary cannot be started, refuses the profile or the registration (the kit's message is included), or exits early.
function defaultProfile(option): "first-party" | "d1" | "minimum";
The profile a test runs under: the option, else the one
bookclerk-plugin test names in BOOKCLERK_DB_TESTKIT_PROFILE, else
minimum.
| Parameter | Type | Description |
|---|---|---|
option |
"first-party" | "d1" | "minimum" | undefined |
The caller's profile option. |
"first-party" | "d1" | "minimum"
The profile name, unchecked.
function kitMigrations(migrations): object[];
Spells a databaseMigrations registration the way the kit reads it.
A plugin may return each operation typed ({ kind: "schema", value },
the PluginMigration shape) or in the short form the
schemaMigrationOp / dataMigrationOp helpers build ({ schema }); the
host accepts both, so the kit is handed the one form it parses. The
registration is first held to the same resource bounds the isolate SDK
applies before the host sees it.
| Parameter | Type | Description |
|---|---|---|
migrations |
readonly PluginMigration[] |
The registration, in either form. |
object[]
The same migrations with every operation as { schema } or { data }.
Error naming the migration when an operation is neither form, or
with code payload_too_large when the registration passes an ABI bound.
function testkitBinary(binary?): string;
Picks the kit binary: the option, then BOOKCLERK_DB_TESTKIT, then the
bare name on PATH.
| Parameter | Type | Description |
|---|---|---|
binary? |
string |
Explicit path, when given. |
string
The command to spawn.
Generated from packages/plugin-sdk at main · View as Markdown