@crvouga/mockingbird-service-payload-cms

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of Payload CMS's collection REST API for test suites: GET /api/<collection> with Payload's paginated envelope (docs, totalDocs, limit, totalPages, page, pagingCounter, hasPrevPage, hasNextPage, prevPage, nextPage) and a where query subset, and GET /api/<collection>/<id>. The marketing collection is seeded with an active referral card, so the backend's referral content comes from the "CMS" deterministically, and the admin plane lets a test change it.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from Payload's REST and query docs and the consumer's response type (payload-cms-response.type.ts).

Install

npm install -D @crvouga/mockingbird-service-payload-cms

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-payload-cms serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

Point PAYLOAD_CMS_API_URL at the emulator. The backend validates it as https-only (validation.schema.ts), so either relax that for loopback or put the emulator behind TLS. Anything that goes wrong (non-2xx, empty docs, bad JSON, a dropped connection) makes the backend fall back to its default referral content, which the presets exercise.

npx mockingbird-payload-cms serve --port 8822
# or seed your own collections: --collections ./cms-seed.json   ({"marketing": [ … ]})

In a test, the application's Payload SDK (@payloadcms/sdk) takes the emulator as its fetch:

import { PayloadSDK } from "@payloadcms/sdk"
import { createRuntime } from "@crvouga/mockingbird-service-payload-cms"

// Test setup: an in-process CMS, with one more marketing document added through the admin plane.
const emulator = createRuntime()
await emulator.fetch(
  new Request("http://cms.test/__admin/collections/marketing/docs", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ name: "Fall", type: "referral", isActive: true, cardTitle: "Fall Rewards" }),
  }),
)

// Application code: Payload's SDK. Only its fetch changes, so requests reach the emulator in
// this process instead of the CMS.
const cms = new PayloadSDK({
  baseURL: "http://cms.test/api",
  fetch: ((url: string, init: RequestInit) =>
    emulator.fetch(new Request(url, init))) as typeof fetch,
})
const page = await cms.find({
  collection: "marketing",
  where: { type: { equals: "referral" }, isActive: { equals: true } },
  limit: 1,
})
// → {docs: [{id: 4, cardTitle: "Fall Rewards", …}], totalDocs: 2, limit: 1, …}

Routes

Only marketing is declared in the contract (it is what our backend reads); any collection seeded through the admin plane is served the same way. Ids are integers (Payload's Postgres adapter), matching the consumer's id: number.

Seed (DEFAULT_MARKETING_DOCS): 1 an inactive referral card, 2 the active referral card, 3 an active banner.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): server_error (500), forbidden (403), collection_not_found (404), no_active_docs (an empty page), malformed_json (200 HTML), unavailable (503 HTML), connection_drop, slow (10 s).

Namespaces

Our backend's fetch sends no credential, so use a /__admin/ns/<name> suffix on PAYLOAD_CMS_API_URL (e.g. http://127.0.0.1:8822/__admin/ns/worker-1) or x-mockingbird-namespace. A request carrying Authorization: <collection> API-Key <key> or a bearer token can also be mapped with PUT /__admin/credentials.

Deliberately not modelled

• Writes through the REST API (create/update/delete), auth endpoints, access control, drafts, versions, locales, relationship population (depth), uploads and GraphQL.
• where operators beyond the subset above (near, within, intersects, all).

API

Part of mockingbird.