9. Testing — @get-bb/plugin-sdk/testing

One import path for a plugin's tier-1 harnesses and the tier-4 conformance check (12 §1: tier 1 proves the kernel invariants a plugin relies on; tier 4 proves every defineService method reaches HTTP, SDK, CLI, tool, and docs). Node only; the product never loads it, and a server build that imports /testing fails (as-built D19). Tiers 2 and 3 (corpus replay, screenshot parity) belong to @bb/test-kit and take the built plugin, not these harnesses (as-built §5).

Spec 01 §10 sketches createKernel + loadPlugin(kernel, { dir }). Built: there is no createKernel; createTestContainer() is the test kernel, loadPlugin takes a built artifact (dir: sources are not compiled: packages/kernel-loader/src/testing/index.ts), and createTestPlugin is the SDK's wrapper that writes the artifact for you. Built wins.

Run a plugin's suite with pnpm exec turbo run typecheck test lint --filter=@get-bb/plugin-<id> (as-built §5). Every plugin ships the four files the example has: contracts, server, app, host tests as applicable (examples/plugins/hello-slot/src/*.test.ts).

9.1 What each harness runs

9.2 createTestPlugin

createTestPlugin(init: CreateTestPluginInit): Promise<TestPluginHandle>. It builds a synthetic artifact from the spec (package.json named @get-bb/plugin-<id> 1.0.0; bb = { id, name: id, description } plus server/contracts/host entry paths for the fields you pass, then the rest of manifest), generates dist/contract.json from contracts, writes a composition with one row per bundled plugin (the plugin's config on its row), and boots createTestLoader with kernelServices: true. With isolation: "worker" the plugin's source becomes npm and its row is inserted through the user layer, so the loader places it in the inline worker (01 §5; spec 01 §10 "or worker to exercise the proxy"; D20: both placements).

9.3 createAppHarness

createAppHarness(init: AppHarnessInit): Promise<AppHarness>. Boot order: IS_REACT_ACT_ENVIRONMENT = true; history.replaceState(path ?? "/"); localStorage/sessionStorage cleared; a synthetic test-shell plugin is prepended when shell is given; each plugin's setup runs once through the collector to produce its bootstrap descriptor (version 1.0.0, generation 1, status: "running"); services are provided on the client container's root; KernelRoot renders inside act; kernel.boot() runs inside act (07 §2). The fake core answers …/kernel-ui/bootstrap/get with the synthesized bootstrap, …/kernel/preferences/get with { value: null, updatedAt: null }, …/kernel/preferences/set with { updatedAt }, your routes by pathname (input from the JSON body or the ?input= query), and everything else with a 404 unknown_method envelope; a route that throws returns the KernelError (or plugin_error) as a 404 envelope.

// hello-slot app.test.ts: wait for a refetch through the real 50 ms debounce
const waitFor = async (h: AppHarness, ok: () => boolean): Promise<void> => {
  for (let i = 0; i < 100; i += 1) { if (ok()) return; await h.act(() => new Promise((r) => setTimeout(r, 10))); }
  throw new Error(`timed out; panel:\n${h.element.innerHTML}`);
};
await h.act(() => h.socket.event("hello-slot/greeted", { name: "cli", count: 7 }));
await waitFor(h, () => text(h, "hello-slot-count") === "count 7");

Rules (D20, README deviations 10–11, examples/plugins/hello-slot/vitest.config.ts):

• setup is synchronous. The harness runs it through the collector to build the descriptor the kernel compares against at load (07 §5.9); a setup that returns a Promise is refused with invalid_contract "setup must be synchronous in the harness". The browser and the build hook await a Promise (§4.1); the harness alone refuses one, so a synchronous setup passes all three.
• Root-scoped children only. A root occupant cannot declare a thread/pane child (07 §5.3). Thread- and pane-scoped slots are tested at the type level until a pane-level mount exists (README "requests": kernel-ui).
• Install happy-dom by hand. Every test file runs in node. app.test.ts installs the DOM at module scope with const dom = await builtinEnvironments["happy-dom"].setup(globalThis, {}) and tears it down in afterAll, instead of a // @vitest-environment happy-dom docblock: the /testing entry also loads the server-tier harness (kernel-loader → kernel-store), whose module scope resolves its migrations directory from a file: import.meta.url that vitest's happy-dom environment rewrites to http:.

9.4 fakeService, fakeShellHost, FakeRealtimeSocket

9.5 fakeRoleContext and host callers

fakeRoleContext(init: FakeRoleContextInit = {}): FakeRoleContext (05 §6.3). Defaults: pluginId: "test-plugin", generation: "1", role: "rpc", name: "main", dataDir: /fake/plugins/host/<pluginId>, tempDir: <dataDir>/tmp, scope: { kind: "none" }. Pass a real temp dir as dataDir when the role writes files (host.test.ts).

Calling a role directly (no createTestPlugin): index entry.roles[role][name] yourself and pass ctx.context, as host.test.ts does for both the environment-provider role and the rpc role's commands table. The index is unknown (§6.1): narrow with typeof handler === "function" before the call, or export the defineHostRole row's typed handlers from host.ts and test those.

9.6 expectDerivedSurfaces

expectDerivedSurfaces(def: ServiceDef, samples: DerivedSurfaceSamples = {}): void (03 §7.4; 12 §2.4 K1). Mandatory in every plugin suite, once per service it defines (D20). It collects every problem and throws one Error listing all of them, prefixed expectDerivedSurfaces(<def.id>).

9.7 Re-exports from the kernel packages

@bb/test-kit is not a plugin dependency; the SDK re-exports the "parked" helpers straight from the kernel packages that own them (test-kit README "Deviations": re-exported, not moved, because turbo refuses a package-graph cycle).

9.8 The four sketches

Trimmed from as-built §5; the full versions are examples/plugins/hello-slot/src/{server,app,host,contracts}.test.ts.

Server tier, both placements (server.test.ts):

import { createTestPlugin } from "@get-bb/plugin-sdk/testing";
const manifest = { id: "hello-slot", provides: { "hello-slot/greeter": { version: "1.0.0" } },
  contributes: { database: true, cli: { commands: ["hello"] }, hostRoles: [{ role: "rpc", name: "echo" }] } };
describe.each(["inproc", "worker"] as const)("hello-slot/greeter (%s)", (isolation) => {
  let plugin: TestPluginHandle;
  beforeEach(async () => { plugin = await createTestPlugin({ manifest, server, host, contracts: [greeter], isolation }); });
  afterEach(() => plugin.dispose());
  it("greets, then reloads", async () => {
    const svc = await plugin.inject(greeter);
    await expect(svc.greet({ name: "bb" })).resolves.toMatchObject({ count: 0 });
    await plugin.reload();
    await expect(svc.greet({ name: "bb" })).rejects.toMatchObject({ code: "stale_handle" });
  });
});

App tier over a fake core (app.test.ts):

import { builtinEnvironments } from "vitest/environments";
import { createAppHarness, fakeService } from "@get-bb/plugin-sdk/testing";
const dom = await builtinEnvironments["happy-dom"].setup(globalThis, {});
afterAll(() => dom.teardown(globalThis));
const harness = await createAppHarness({
  plugins: [{ id: "hello-slot", app }],
  path: "/hello",
  routes: { "/api/v1/hello-slot/greeter/greet": (input) => greeting(nameOf(input), count) },
  services: [fakeService(greeter, { greet: async ({ name }) => greeting(name, count), count: …, hostGreet: … })],
});
await harness.act(() => harness.socket.event("hello-slot/greeted", { name: "cli", count: 7 }));
await waitFor(harness, () => harness.element.querySelector('[data-testid="hello-slot-count"]')?.textContent === "count 7"); // §9.3: after the 50 ms debounce

Host tier without a process (host.test.ts):

import { fakeRoleContext } from "@get-bb/plugin-sdk/testing";
const ctx = fakeRoleContext({ pluginId: "hello-slot", role: "environment-provider", name: "scratch", dataDir });
const handle = await scratch.provision({ envId: "env_1", options: {}, source, signal, progress }, ctx.context);
expect(handle).toMatchObject({ kind: "local-path" });
expect(ctx.signals).toEqual([]);

Derived surfaces (contracts.test.ts):

import { expectDerivedSurfaces } from "@get-bb/plugin-sdk/testing";
it("passes the derived-surface conformance check (03 §7.4)", () => {
  expectDerivedSurfaces(greeter, {
    greet: { input: { name: "bb" }, output: sample },
    count: { input: { name: "bb" }, output: sample },
    hostGreet: { input: { name: "bb" }, output: hostSample },
  });
});

9.9 Types index