libmock

Shared mocks and test fixtures so every library and service tests the same way.

Usage

import {
  // Mock primitive (replaces node:test's mock.fn)
  spy,
  // Config / storage / logger / fs
  createMockConfig,
  createMockStorage,
  createSilentLogger,
  createMockFs,
  // gRPC / RPC
  createMockGrpcFn,
  MockMetadata,
  createMockObserverFn,
  createMockTracer,
  createMockAuthFn,
  // Clients
  createMockMemoryClient,
  createMockLlmClient,
  createMockAgentClient,
  createMockVectorClient,
  createMockGraphClient,
  createMockToolClient,
  // Infra
  createMockSupabaseClient,
  createMockS3Client,
  createTurtleHelpers,
  createMockProcess,
  withSilentConsole,
  createMockQueries,
  // Agent-aligned engineering standard fixtures (pathway data)
  createTestStandard,
  createTestLevel,
  createTestSkill,
  createTestDiscipline,
  createTestTrack,
  createTestBehaviour,
  createTestCapability,
  createTestDriver,
  createTestPerson,
  createTestRoster,
  createTestEvidenceRow,
  // libharness stream/message helpers
  createToolUseMsg,
  createTextBlockMsg,
  createTestTrace,
  collectStream,
  stripAnsi,
  writeLines,
  createMockAgentQuery,
  // Assertions
  assertThrowsMessage,
  assertRejectsMessage,
  createDeferred,
  // Caching
  memoizeAsync,
  memoizeOnSubject,
} from "@forwardimpact/libmock";

The full export list lives in src/index.js. Subpath entries @forwardimpact/libmock/fixture and @forwardimpact/libmock/mock remain for narrower imports.

Collaborators

Canonical fakes for the runtime collaborator surfaces. Every test that needs a fake imports it from here so production and test wire the same shape. createTestRuntime assembles them into a frozen bag that mirrors libutil's createDefaultRuntime.

| Surface | Production shape | Factory | Example | |---|---|---|---| | clock | now() / sleep(ms) | createMockClock | const clock = createMockClock(); clock.advance(1000); | | fs | node:fs / node:fs/promises | createMockFs | const fs = createMockFs({ "/a.txt": "hi" }); | | proc | the process global | createMockProcess | const proc = createMockProcess({ cwd: "/work", env: { K: "v" } }); | | subprocess | node:child_process | createMockSubprocess | const sub = createMockSubprocess({ responses: { git: { stdout: "ok" } } }); | | finder | libutil Finder | createMockFinder | const finder = createMockFinder({ files: { "/p/package.json": true } }); | | git-client | libutil GitClient | createMockGitClient | const git = createMockGitClient({ responses: { revListCount: 3 } }); | | gh-client | libutil GhClient | createMockGhClient | const gh = createMockGhClient({ responses: { prCreate: "url" } }); | | runtime bag | libutil createDefaultRuntime | createTestRuntime | const rt = createTestRuntime({ clock: createMockClock() }); | | graph-index | libgraph GraphIndex + n3 Store triple | createGraphIndexFixture | const { graphIndex } = createGraphIndexFixture({ GraphIndex, Store }); | | grpc health def | stripped { Check: { path, … } } shape | createMockGrpcHealthDefinition | const def = createMockGrpcHealthDefinition(); | | repl env | readline/process/os/formatter/storage bundle | createReplEnvironment | const { readline, process } = createReplEnvironment(); |

test/runtime-completeness.test.js asserts that every field on libutil's Runtime typedef has a matching fake here. So the fakes cannot drift behind the bag.

When to extend libmock

Check src/index.js before you add a helper locally in a test file. If the helper does not exist, and two or more files would use it, add it to libmock in the same PR. Do not inline it. See CONTRIBUTING.md READ-DO and DO-CONFIRM checklists for the enforced policy. See .jidoka/invariants/libmock.rules.mjs for the pre-commit guard that flags inline reimplementations.

spy vs node:test's mock.fn

spy() matches mock.fn's shape exactly:

const fn = spy((x) => x * 2);
fn(5);
fn.mock.calls[0].arguments; // [5]
fn.mock.calls[0].result;    // 10
fn.mock.callCount();        // 1
fn.mock.resetCalls();
fn.mock.mockImplementation((x) => x + 1);

Prefer spy over node:test's mock.fn. spy works under both bun test (the default runner) and node --test.