bookclerk_db_testkit

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

Last updated View as Markdown

Contract conformance test kit for code that talks to a Bookclerk database plugin.

Production hosts reach every database through an external adapter guest that refuses interactive transactions and enforces the limits it advertised. A plain in-memory SQLite connection does neither, so a test that passes on one can still fail on the hosted demo. This kit opens an in-memory library whose connection behaves like the guest:

adapter is the other side of the same contract: a conformance suite a database adapter plugin runs on an empty unit, in process or as its spawned guest, to prove it keeps the SQL-v1 contract the host relies on.

fixtures generates realistic rows near the caps, and paging checks that a paged listing returns what the full listing returns. Ordinary SeaORM reads through TestDatabase::connection are held to the engine proxy's first-party caps, as on the shipped sqlite adapter.

Item Kind Summary
UnknownProfile struct A BOOKCLERK_DB_TESTKIT_PROFILE value that names no profile.
TestDatabase struct An in-memory library that behaves like an external database plugin.
selected_profile function The profile of the current bookclerk-plugin test run, or Profile::Minimum when the suite runs on its own.
PROFILE_ENV constant The environment variable bookclerk-plugin test sets to the profile of the current run.

Re-exports

Modules

  • adapter: Conformance suite for database adapter plugins.
  • binding: A plugin-owned database that behaves like a granted [[databases]] binding on a deployed host.
  • fixtures: Realistic row contents sized against a capability advertisement.

Structs

UnknownProfile

pub struct UnknownProfile(pub String);

A BOOKCLERK_DB_TESTKIT_PROFILE value that names no profile.

Implements: Clone, Debug, Display, Eq, Error, PartialEq

TestDatabase

pub struct TestDatabase {
    /* private fields */
}

An in-memory library that behaves like an external database plugin.

Open one with TestDatabase::open and run the code under test against TestDatabase::store.

TestDatabase::open

pub async fn open(profile: Profile) -> Result<Self>

Opens an empty in-memory library with the host schema under profile.

Errors

Returns the engine or schema error when the database cannot be opened.

TestDatabase::open_all

pub async fn open_all() -> Result<Vec<Self>>

Opens one database per Profile::ALL entry.

Errors

Returns the first open error.

TestDatabase::profile

pub fn profile(&self) -> Profile

The enforced profile.

TestDatabase::capabilities

pub fn capabilities(&self) -> &DbCapabilities

The enforced capability advertisement.

TestDatabase::store

pub fn store(&self) -> &LibraryStore

The library store under test.

TestDatabase::connection

pub fn connection(&self) -> &DatabaseConnection

The begin-refusing connection, for reads a test makes directly.

TestDatabase::refused_begins

pub fn refused_begins(&self) -> u32

How many interactive transactions the code under test tried to open.

A host write that works on an external adapter leaves this at zero.

TestDatabase::batch_sizes

pub fn batch_sizes(&self) -> Vec<usize>

Statement counts of every batch sent so far, in arrival order, including batches a fault turned away.

TestDatabase::execute_batch

pub async fn execute_batch(
    &self,
    request: ExecuteRequest,
) -> Result<ExecuteReply, PluginError>

Runs one host-authored batch through the profile; see ProfileStore::execute_batch.

Errors

Returns the typed limit_exceeded error when the request or the reply exceeds a cap, invalid_params when the batch does not typecheck against the host schema, and unavailable for an injected fault or an engine failure.

TestDatabase::lose_next_replies

pub fn lose_next_replies(&self, n: u32)

The next n batches are applied but their replies are lost: the caller sees unavailable, the way a dropped RPC reply looks, and a retry with the same operation id must not repeat the write.

TestDatabase::lock_next_requests

pub fn lock_next_requests(&self, n: u32)

The next n batches are refused with SQLite lock contention before anything is applied, the way a busy file lock answers.

Implements: Debug

Functions

selected_profile

pub fn selected_profile() -> Result<Profile, UnknownProfile>

The profile of the current bookclerk-plugin test run, or Profile::Minimum when the suite runs on its own.

A Rust suite opens its TestDatabase or BindingDatabase under this profile so each of the command's runs exercises a different advertisement, as the TypeScript and Python kits do by default.

Errors

Returns UnknownProfile when the variable is set to a name outside Profile::ALL.

Constants

PROFILE_ENV

pub const PROFILE_ENV: &str = "BOOKCLERK_DB_TESTKIT_PROFILE";

The environment variable bookclerk-plugin test sets to the profile of the current run.

Generated from crates/bookclerk-db-testkit at main · View as Markdown