@kybernesis/brain-testkit

Testing tools for the Cortex brain library — a parity harness, storage conformance cases, an isolated tenant factory, and an LLM stub. This is what you use to prove a provider implementation conforms to the contracts, and to test code that builds on brain-core.

Install

pnpm add -D @kybernesis/brain-testkit

What's in it

runParityHarness — prove two backends agree

import { runParityHarness } from '@kybernesis/brain-testkit/parity';

Drives a sequence of brain operations against two StorageProvider implementations and asserts their resulting database state matches. The tool that guards "this new backend behaves exactly like the canonical one."

Storage conformance cases

import { storageConformanceCases } from '@kybernesis/brain-testkit/conformance';

A reusable suite a StorageProvider implementation runs against itself to verify it satisfies the @kybernesis/brain-contracts interface. (brain-storage-sqlite uses these in its own test suite.)

createTestTenant — isolated brain per test

import { createTestTenant } from '@kybernesis/brain-testkit/helpers';

const { tenant, cleanup } = createTestTenant('my-suite');
afterEach(cleanup);

Builds a TenantContext rooted in a unique tmpdir, so parallel tests never share SQLite files.

makeLLMStub — a deterministic LLM seam

import { makeLLMStub } from '@kybernesis/brain-testkit';
import { setLLMProvider } from '@kybernesis/brain-core';

const llm = makeLLMStub({ 'extract entities': '["Ada"]', '*': '[]' });
setLLMProvider(llm);
// …run code…
expect(llm.calls).toHaveLength(1);   // every call is recorded (prompt + opts)

Maps prompt-substrings to canned responses ('*' is the wildcard fallback) and records every invocation on .calls so you can assert what the kernel passed through.

Subpath exports

. (stub + tenant + re-exports), ./parity, ./conformance, ./helpers.

Notes

• ESM-only, TypeScript strict. Intended as a devDependency.
• Part of Cortex — @kybernesis/brain-*.