@rulvar/testing 1.0.0

package/dist/matchers.d.ts

@@ -0,0 +1,32 @@
+import { r as TestRunHandle } from "./test-engine-kYp9C72n.js";
+
+//#region src/matchers.d.ts
+interface MatcherResult {
+  pass: boolean;
+  message: () => string;
+}
+/** expect(run).toHaveCalledAgent('reviewer', { times: 3 }) */
+declare function toHaveCalledAgent(received: TestRunHandle<unknown>, agentType: string, options?: {
+  times?: number;
+}): Promise<MatcherResult>;
+/** expect(run).toStayUnderBudget({ usd: 5 }) */
+declare function toStayUnderBudget(received: TestRunHandle<unknown>, options: {
+  usd: number;
+}): Promise<MatcherResult>;
+/** The bundle for expect.extend (Vitest 4 and Jest compatible shapes). */
+declare const rulvarMatchers: {
+  toHaveCalledAgent: typeof toHaveCalledAgent;
+  toStayUnderBudget: typeof toStayUnderBudget;
+};
+declare module "vitest" {
+  interface Matchers<T = any> {
+    toHaveCalledAgent(agentType: string, options?: {
+      times?: number;
+    }): Promise<T>;
+    toStayUnderBudget(options: {
+      usd: number;
+    }): Promise<T>;
+  }
+}
+//#endregion
+export { MatcherResult, rulvarMatchers, toHaveCalledAgent, toStayUnderBudget };

package/dist/matchers.js

@@ -0,0 +1,32 @@
+//#region src/matchers.ts
+async function settled(handle) {
+	await handle.result;
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	return handle;
+}
+/** expect(run).toHaveCalledAgent('reviewer', { times: 3 }) */
+async function toHaveCalledAgent(received, agentType, options) {
+	const calls = (await settled(received)).eventsSeen.filter((event) => event.type === "agent:end" && event.agentType === agentType).length;
+	const expected = options?.times;
+	const pass = expected === void 0 ? calls > 0 : calls === expected;
+	return {
+		pass,
+		message: () => expected === void 0 ? `expected run ${pass ? "not " : ""}to have called agent '${agentType}' (called ${calls} times)` : `expected run to have called agent '${agentType}' ${expected} times, saw ${calls}`
+	};
+}
+/** expect(run).toStayUnderBudget({ usd: 5 }) */
+async function toStayUnderBudget(received, options) {
+	const outcome = await received.result;
+	const spent = outcome.cost.totalUsd;
+	return {
+		pass: spent < options.usd && outcome.status !== "exhausted",
+		message: () => `expected run to stay under ${options.usd.toFixed(4)} USD; spent ${spent.toFixed(4)} USD with outcome '${outcome.status}'`
+	};
+}
+/** The bundle for expect.extend (Vitest 4 and Jest compatible shapes). */
+const rulvarMatchers = {
+	toHaveCalledAgent,
+	toStayUnderBudget
+};
+//#endregion
+export { rulvarMatchers, toHaveCalledAgent, toStayUnderBudget };

package/dist/test-engine-kYp9C72n.d.ts

@@ -0,0 +1,81 @@
+import { AgentProfile, ChatEvent, ChatRequest, CreateEngineOptions, Engine, InMemoryStore, ModelCaps, ProviderAdapter, RunHandle, RunOptions, WireError, Workflow, WorkflowEvent } from "@rulvar/core";
+
+//#region src/fake-adapter.d.ts
+/** What a responder sees about the call. */
+interface FakeCall {
+  prompt: string;
+  agentType?: string;
+  label?: string;
+  req: ChatRequest;
+}
+/**
+* A static string (plain text output), a static value (structured output),
+* or a function of the call. Thrown errors become terminal error events.
+* fakeToolCalls() and fakeWireError() values script tool-calling turns and
+* typed wire failures (M3).
+*/
+type FakeResponder = string | ((call: FakeCall) => unknown) | object;
+/** Marker value: the model answers this turn with tool calls (M3). */
+interface FakeToolCallsValue {
+  __fake: "tool-calls";
+  calls: Array<{
+    name: string;
+    args: unknown;
+  }>;
+}
+/** Scripts a tool-calling turn from a responder. */
+declare function fakeToolCalls(...calls: Array<{
+  name: string;
+  args: unknown;
+}>): FakeToolCallsValue;
+/** Marker value: the stream terminates with this typed wire error (M3). */
+interface FakeWireErrorValue {
+  __fake: "wire-error";
+  error: WireError;
+}
+/** Scripts a typed wire failure (e.g. a retryable rate limit). */
+declare function fakeWireError(error: WireError): FakeWireErrorValue;
+interface FakeAdapterOptions {
+  /**
+  * Patterns match on agentType, label, or a regex over the prompt; '*'
+  * is the fallback (docs/09, section "Tier 1").
+  */
+  agents: Record<string, FakeResponder>;
+}
+declare const FAKE_MODEL = "fake-model";
+declare const FAKE_MODEL_REF = "fake:fake-model";
+declare class FakeAdapter implements ProviderAdapter {
+  readonly id = "fake";
+  private readonly agents;
+  private readonly mintId;
+  /** Every request this adapter served, in order. */
+  readonly calls: FakeCall[];
+  constructor(options: FakeAdapterOptions);
+  caps(this: void): ModelCaps;
+  private match;
+  stream(req: ChatRequest): AsyncIterable<ChatEvent>;
+}
+//#endregion
+//#region src/test-engine.d.ts
+/** A RunHandle that records its own event stream for the matchers. */
+interface TestRunHandle<R> extends RunHandle<R> {
+  /** Every event emitted by the run, in seq order. */
+  eventsSeen: WorkflowEvent[];
+}
+interface TestEngine extends Engine {
+  run<A, R>(wf: Workflow<A, R>, args: A, opts?: RunOptions): TestRunHandle<R>;
+  /** The adapter instance, for call-level assertions. */
+  fake: FakeAdapter;
+  /** The backing journal store (journal capture for replay-strict tests). */
+  store: InMemoryStore;
+}
+interface CreateTestEngineOptions {
+  agents: Record<string, FakeResponder>;
+  /** Additional profiles; every agents key is auto-registered as an empty profile. */
+  profiles?: Record<string, AgentProfile>;
+  budgetDefaults?: CreateEngineOptions["budgetDefaults"];
+  concurrency?: CreateEngineOptions["concurrency"];
+}
+declare function createTestEngine(options: CreateTestEngineOptions): TestEngine;
+//#endregion
+export { FAKE_MODEL as a, FakeAdapterOptions as c, FakeToolCallsValue as d, FakeWireErrorValue as f, createTestEngine as i, FakeCall as l, fakeWireError as m, TestEngine as n, FAKE_MODEL_REF as o, fakeToolCalls as p, TestRunHandle as r, FakeAdapter as s, CreateTestEngineOptions as t, FakeResponder as u };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@rulvar/testing",
+  "version": "1.0.0",
+  "description": "rulvar test harness: createTestEngine, FakeAdapter, VCR cassettes, replay-strict runs, matchers.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./matchers": {
+      "types": "./dist/matchers.d.ts",
+      "default": "./dist/matchers.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@rulvar/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3",
+    "zod": "^4.4.3",
+    "@rulvar/compat": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/rulvar.git",
+    "directory": "packages/testing"
+  },
+  "homepage": "https://rulvar.com",
+  "bugs": {
+    "url": "https://github.com/o-stepper/rulvar/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pack-check": "publint --pack pnpm && attw --pack . --profile esm-only"
+  }
+}