@sanity-labs/workflow-engine-explore-test-client

An in-memory fake of @sanity/client for local testing. Implements the data-plane subset (queries, mutations, transactions) against a groq-js evaluator and a closure-scoped document store. Created fresh per test — no global state, no network.

Status: 0.x POC. Useful standalone for testing any code that takes a SanityClient-shaped dep, even outside the workflow engine.

npm install -D @sanity-labs/workflow-engine-explore-test-client

Quickstart

import { createTestClient } from "@sanity-labs/workflow-engine-explore-test-client";

const client = createTestClient({
  documents: [
    { _id: "article-1", _type: "article", title: "Hello", state: "draft" },
    { _id: "article-2", _type: "article", title: "World", state: "approved" },
  ],
});

// fetch — GROQ via groq-js against the in-memory store
const approved = await client.fetch<{ _id: string }[]>(
  `*[_type == "article" && state == $s]{_id}`,
  { s: "approved" },
);
// → [{ _id: "article-2" }]

// getDocument — single-doc lookup
const doc = await client.getDocument("article-1");

// patch + commit
await client.patch("article-1").set({ state: "approved" }).commit();

// createOrReplace — upsert
await client.createOrReplace({ _id: "article-3", _type: "article", title: "New" });

// transaction — atomic batch
await client.transaction()
  .patch("article-1", (p) => p.set({ reviewedBy: "alice" }))
  .patch("article-2", (p) => p.set({ reviewedBy: "alice" }))
  .commit();

What it implements

The methods relevant to anything that talks to the Sanity data plane match @sanity/client's signatures:

• fetch(query, params?) — GROQ via groq-js
• getDocument(id) / getDocuments(ids)
• create(doc) / createOrReplace(doc) / createIfNotExists(doc)
• delete(id)
• patch(id) → chain of .set / .setIfMissing / .unset / .inc / .dec / .append / .prepend / .insert / etc. → .commit()
• transaction() → fluent batch of operations → .commit() (atomic)
• action({ actionType, … }) — supports a small subset (used by the engine's sanity.release.publish effect handler)

What it intentionally does not implement:

• listen (real-time subscriptions)
• Asset uploads
• Project actions, agent actions
• Perspectives (drafts, published, raw) — all docs are visible at all times
• HTTP request() — the workflow engine's permission resolver short-circuits when this is absent (graceful skip of the ACL gate)

If you need one of the above for a real-looking test, vendor in a stub or use MSW for HTTP intercepts.

Design constraints

• Closure-scoped isolation. createTestClient({ documents }) returns a client whose store is local to that closure. Two clients created in two tests do not see each other's writes. Pass the same client to two consumers if they need to share a store (e.g. multi-tenant scope tests in the engine bench).
• Drop-in shape. The methods listed above accept the same arg shapes as @sanity/client, so any code typed against SanityClient (or a narrow subset) can take a TestClient without an adapter. Compatibility is structural, not nominal.
• groq-js directly. Same GROQ evaluator the engine uses, against the in-memory document set. What groq-js supports, this supports. What it doesn't (some && short-circuit edge cases, custom functions), this doesn't either.

Reading the store directly

client.snapshot() returns the raw document array. Useful for assertions:

const docs = client.snapshot();
expect(docs.find((d) => d._id === "article-1")?.state).toBe("approved");

For workflow-engine tests specifically, prefer the bench read helpers (bench.getInstance, bench.currentStage, etc.) — they apply the engine's tag scoping. client.snapshot() does not.

License

UNLICENSED — internal Sanity labs exploration.