bookclerk_db_testkit
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:
begin()on the connection is refused the way the adapter refuses it, and the refusal is counted (TestDatabase::refused_begins).- Every host batch goes through an executor that applies the
Profile's capability advertisement on the request and on the reply, answering a typedlimit_exceedederror. - Lost replies and lock contention can be injected
(
TestDatabase::lose_next_replies,TestDatabase::lock_next_requests).
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. |
adapter::assert_adapter_conformsadapter::run_adapter_suiteadapter::AdapterReportbinding::BindingDatabasebookclerk_library::test_support::pagingbookclerk_library::test_support::Profilebookclerk_library::test_support::INTERACTIVE_TRANSACTIONS_REFUSED
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.
pub struct UnknownProfile(pub String);
A BOOKCLERK_DB_TESTKIT_PROFILE value that names no profile.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
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.
pub async fn open(profile: Profile) -> Result<Self>
Opens an empty in-memory library with the host schema under profile.
Returns the engine or schema error when the database cannot be opened.
pub async fn open_all() -> Result<Vec<Self>>
Opens one database per Profile::ALL entry.
Returns the first open error.
pub fn profile(&self) -> Profile
The enforced profile.
pub fn capabilities(&self) -> &DbCapabilities
The enforced capability advertisement.
pub fn store(&self) -> &LibraryStore
The library store under test.
pub fn connection(&self) -> &DatabaseConnection
The begin-refusing connection, for reads a test makes directly.
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.
pub fn batch_sizes(&self) -> Vec<usize>
Statement counts of every batch sent so far, in arrival order, including batches a fault turned away.
pub async fn execute_batch(
&self,
request: ExecuteRequest,
) -> Result<ExecuteReply, PluginError>
Runs one host-authored batch through the profile; see
ProfileStore::execute_batch.
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.
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.
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
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.
Returns UnknownProfile when the variable is set to a name outside
Profile::ALL.
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