Docs / Guides / Testing

Fast, deterministic tests

Use the memory adapter for application and agent behavior, inject fetch for provider protocol tests, and run the shared contract against custom adapters. No live credentials are required.

Memory adapter

test-setup.ts
import { createWorkClient } from "work-sdk";
import { memoryWorkAdapter, workItemFixture } from "work-sdk/testing";

const adapter = memoryWorkAdapter({
  items: [workItemFixture({
    id: "42",
    identifier: "TEST-42",
    title: "Initial title",
  })],
  now: () => new Date("2026-01-01T00:00:00Z"),
});

const work = createWorkClient({
  adapter,
  now: () => new Date("2026-01-01T00:00:00Z"),
});

The memory adapter implements the full contract, clones returned values, advances revisions, supports capability overrides, and honors abort signals.

Test critical scenarios

  • Prepared plan contains the expected exact diff.
  • Mutating a plan causes fingerprint rejection.
  • Warnings block commit until explicitly acknowledged.
  • A repeated key returns replayed: true.
  • Concurrent commits with one key perform one mutation.
  • A stale revision raises WorkConflictError.
  • Abort signals prevent provider calls.

Provider protocol tests

Every first-party adapter accepts an injected WHATWG-compatible fetch. Assert URLs, authentication, escaped queries, request bodies, pagination, readback, and error normalization without network traffic.

azure-adapter.test.ts
const fetch = vi.fn(async (input, init) => {
  const url = new URL(String(input));

  if (url.pathname.endsWith("/_apis/wit/wiql")) {
    return Response.json({ workItems: [{ id: 42 }] });
  }

  return Response.json(azureWorkItemFixture);
});

const adapter = azureDevOps({
  organization: "acme",
  project: "Platform",
  fetch,
});

Prefer real Request, Response, and Headers objects in mocks. They catch casing, status, body-consumption, and header behavior that plain objects hide.

Custom adapter contract

The repository exports a reusable internal conformance suite for first-party development. External adapters should verify the same invariants: stable identity, cloned reads, pagination, revision advancement, conflicts, comments, and cancellation.