bookclerk_plugin_sdk.testkit

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Contract conformance test kit: a plugin database binding like the host's.

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. create_test_database gives a pytest 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.

from bookclerk_plugin_sdk.testkit import TEST_DATABASE_PROFILES, create_test_database

for profile in TEST_DATABASE_PROFILES:
    async with create_test_database(profile=profile, migrations=MIGRATIONS) as db:
        await db.binding.prepare("INSERT INTO notes (id, body) VALUES (?, ?)").bind(1, "hi").run()
        rows = (await db.binding.prepare("SELECT body FROM notes").all()).results

The binary is found through the BOOKCLERK_DB_TESTKIT environment variable or the binary argument, 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 CPython, not inside an isolate.

Name Kind Summary
TestDatabase class A served test binding and the process behind it.
testkit_binary function Pick the kit binary.
default_profile function Pick the profile a test runs under.
create_test_database function Spawn the kit under profile with migrations applied.
TestDatabaseProfile constant One of TEST_DATABASE_PROFILES.
TEST_DATABASE_PROFILES constant

Classes

TestDatabase

class TestDatabase

A served test binding and the process behind it.

Use it as an async context manager, or call close when the test ends; the in-memory unit goes with the process.

TestDatabase.init

def __init__(self, profile: TestDatabaseProfile, process: Any, serving: _Serving) -> None

Wrap a running kit process.

Args

  • profile: The profile being enforced.
  • process: The asyncio subprocess serving the binding.
  • serving: Its announcement.

TestDatabase.limits

async def limits(self) -> DbCapabilities

Read the profile's advertisement: the caps every batch is held to.

Returns

The capability advertisement, as binding.limits() reports it.

TestDatabase.close

async def close(self) -> None

Stop the kit process; the in-memory unit goes with it.

Functions

testkit_binary

def testkit_binary(binary: str | None=None) -> str

Pick the kit binary.

Args

  • binary: Explicit path, when given.

Returns

binary, else BOOKCLERK_DB_TESTKIT from the environment, else the bare bookclerk-db-testkit name resolved on PATH.

default_profile

def default_profile(option: TestDatabaseProfile | None=None) -> TestDatabaseProfile

Pick the profile a test runs under.

Args

  • option: The caller's profile argument.

Returns

option when given, else the profile bookclerk-plugin test names in BOOKCLERK_DB_TESTKIT_PROFILE, else minimum. Not validated.

create_test_database

async def create_test_database(
    profile: TestDatabaseProfile | None=None,
    migrations: list[dict[str, Any]] | None=None,
    *,
    binary: str | None=None,
) -> TestDatabase

Spawn the kit under profile with migrations applied.

Args

  • profile: Capability profile to enforce. Defaults to BOOKCLERK_DB_TESTKIT_PROFILE when bookclerk-plugin test sets it, else minimum, the strictest.
  • migrations: The plugin's database_migrations registration (each {"id": ..., "operations": [{"schema": sql} | {"data": sql}, ...]}), applied the way the host applies it at enrollment.
  • binary: Path of the bookclerk-db-testkit binary; see the module docs for the default.

Returns

The served binding and its process; close it when the test ends.

Raises

  • ValueError: When profile is not one of TEST_DATABASE_PROFILES.
  • RuntimeError: When the binary cannot be started, refuses the profile or the registration (its message is included), or exits early.

Constants

TestDatabaseProfile

TestDatabaseProfile = Literal['first-party', 'd1', 'minimum']

One of TEST_DATABASE_PROFILES.

TEST_DATABASE_PROFILES

TEST_DATABASE_PROFILES: tuple[TestDatabaseProfile, ...] = ('first-party', 'd1', 'minimum')

Generated from packages/plugin-sdk-python at main · View as Markdown