@cef-ai/testing

Simulator harness for CEF agents — testAgent for single-agent in-process tests, testPlatform for multi-agent tests with a vault simulation.

Install

pnpm add -D @cef-ai/testing

Import the harness directly from @cef-ai/testing in test files:

import { testAgent, testPlatform } from "@cef-ai/testing";

testAgent quickstart

testAgent(AgentClass, opts) constructs an in-memory simulator around a single agent class. It wires ctx.cubby to per-alias SQLite, ctx.fetch to a URL-pattern mock, ctx.models[alias] to stubs, and ctx.publish to a collector you can assert on.

import { describe, it, expect, afterEach } from "vitest";
import { testAgent, type TestHarness } from "@cef-ai/testing";
import Echo from "../src/agent.js";

describe("echo", () => {
  let h: TestHarness | undefined;
  afterEach(() => h?.dispose());

  it("acks user_message", async () => {
    h = testAgent(Echo, {
      cubbies: [{ alias: "history", migrations: "./migrations/history" }],
    });
    const events = await h.dispatch({
      type: "user_message",
      payload: { text: "hello" },
    });
    expect(events.map((e) => e.type)).toContain("ack");
  });
});

testPlatform quickstart

testPlatform({ agents, models, ... }) lifts the harness into a multi-agent world: each agent runs in its own simulator, a shared vault routes events between them, and the test drives interactions through vault.agents / vault.events. Use this when an agent talks to peers or when an application client (your "app") publishes into the vault.

import { describe, it, expect, afterEach } from "vitest";
import { testPlatform, createModelMock, type TestPlatform } from "@cef-ai/testing";
import Assistant from "../agent/src/assistant.js";

describe("assistant + app", () => {
  let p: TestPlatform | undefined;
  afterEach(() => p?.dispose());

  it("answers a user message", async () => {
    const llm = createModelMock();
    llm.expect({ prompt: "hi" }).respond({ text: "hello back" });

    p = testPlatform({
      agents: {
        assistant: {
          source: Assistant,
          cubbies: [{ alias: "history", migrations: "./migrations/history" }],
        },
      },
      models: { llm },
    });

    await p.vault.agents.connect({ agentId: "assistant" });
    // ...drive the vault, assert published events / cubby state
  });
});

API summary

| Symbol | Returns | Notes | | --- | --- | --- | | testAgent(AgentClass, opts?) | TestHarness | Single-agent simulator. Reads AGENT_METADATA to find decorated handlers. | | testPlatform(opts) | TestPlatform | Multi-agent simulator with a shared vault, model registry, and per-agent cubbies. | | mockAgent(spec) | MockAgentDescriptor | Peer descriptor for testPlatform — drop in for an agent you don't want to bring into the test bundle. | | fromMarketplace(url) | MockAgentDescriptor | v1: throws (not yet wired). v2: will fetch a published bundle. | | createModelMock() | ModelMockHandle | Expectation-builder model handle: mock.expect(input).respond(output). |

TestHarness exposes:

• dispatch({ type, payload, from? }) — drive a single event; returns the publishes from this call.
• published — every publish since construction (cumulative log).
• cubby(alias) — CubbyHandle for assertions.
• runInCubby(alias, fn) — run with both the public handle and the raw better-sqlite3 database for sync, prepared-statement assertions.
• start() / close(reason?) — drive @OnStart / @OnClose.
• lifecycle — { state: "idle" | "started" | "closed", terminalReason?: ... }.
• snapshot() / restore(snap) — capture and restore cubbies + clock + publish log.
• replay(jsonlPath) — feed a JSONL fixture of events through the harness.
• advanceTime(ms) / now() — manipulate the injected clock.
• fetchMock() — URL-pattern fetch mock attached to ctx.fetch.
• models — the model handle map attached to ctx.models.
• dispose() — release SQLite handles. Idempotent.

TestPlatform exposes:

• vault — the simulated vault (agents.connect, event streams, scoped per-conversation channels).
• runInCubby(agentId, alias, fn) — assert on a specific agent's cubby.
• dispose() — tear down every per-agent simulator.

Companion packages

• @cef-ai/agent-sdk — the decorators and types the harness is testing.
• @cef-ai/cli — cef build / cef typegen for the build that these tests run alongside.

References

• Agent SDK spec: ../../../company-memory-bank/specs/platform/03-components/agent-sdk.md §9 (testing surface).
• Runtime integration contract: ../../../company-memory-bank/specs/platform/03-components/sdk-runtime-integration-contract.md.

The ../company-memory-bank/... paths point at an internal sibling repo and are not browsable from a fresh clone.