@noverax/courier-mock
v0.7.0
Published
Mock servers for Courier: typed handlers, a SQLite-backed store, scenarios and network faults, with test utilities, contract tests and fixtures
Maintainers
Readme
Overview
Declare mocks in courier.mocks.ts, beside courier.config.ts, and Studio runs them: routes and records generated from each endpoint's schemas, overrides checked against the source's own types, and a SQLite store that keeps what your app created. The same package gives your tests a mock client, factories, recordings of a real API and contract tests.
Install
npm install --save-dev @noverax/courier-mockIt works with the app's own @noverax/courier. It also needs hono, and a mock server — one Studio runs, or one from /server — needs @hono/node-server. Add the ones the app does not depend on already, for development only:
npm install --save-dev hono @hono/node-serverLeave out any the app already lists under dependencies: --save-dev would move it out of them, and a production install would then go without it.
Mock servers in Studio
Declare mocks in courier.mocks.ts, beside courier.config.ts: its default export is defineMocks({ ... }), with one defineMockServer(...) under each key. Studio lists each mock by its key, generates its routes and data from its source, and runs it — at launch when autoStart is set, or when you start it from the Mocks view. Studio's mock wizard can write the declarations for you; see Add mocks from Studio.
The mocks have a file of their own because courier.config.ts is also loaded in production — by the standalone server, and by attachRuntime() — where this package is not installed. Only Studio reads courier.mocks.ts. courier.config.ts has no mocks key: defineConfig does not type-check with one, and Studio reads mocks from nowhere else.
// src/api.ts
import { courier, defineApi, defineGroup } from "@noverax/courier/define"
type User = { id: number; name: string }
const { endpoint } = courier()
const users = defineGroup({
prefix: "users",
endpoints: {
getAll: endpoint.get("").response<User[]>(),
getById: endpoint.get(":id").variables<{ id: number }>().response<User>(),
},
})
export const api = defineApi({ baseURL: "https://api.example.com", groups: { users } })// courier.config.ts
import { defineConfig } from "@noverax/courier/config"
import { api } from "./src/api"
export default defineConfig({ sources: { api } })// courier.mocks.ts
import { defineMocks, defineMockServer } from "@noverax/courier-mock"
import { api } from "./src/api"
export default defineMocks({
api: defineMockServer({
source: api,
port: 7001,
autoStart: true,
seed: { users: 5 },
overrides: (mock) => {
mock("users", "getById").rejects(404, { message: "Not found" })
},
}),
})sourceis the source object the mock serves. Import it from where the config does, as above, or read it from the config —import courierConfig from "./courier.config", thensource: courierConfig.sources.api— as Studio's wizard writes it. That form needs a config whose default export isdefineConfig({ sources }): a config that exportssourcesby name only loads, but a default import of it does not type-check. In a"type": "module"package whose tsconfig resolves modules as Node does (node16ornodenext), import./courier.config.jsinstead; TypeScript asks for the extension there, and the wizard writes it that way. Studio loadscourier.mocks.tstogether with the config, as one module graph, so a module both import runs once, and either way the mock holds the very source object the config declares.- The file may also be named
courier.mocks.mts,.cts,.js,.mjsor.cjs. Studio looks for these names in that order, in the directory that holdscourier.config, and loads the first it finds: acourier.mocks.tsthere hides acourier.mocks.jsbeside it. A TypeScript file loads as it is, with extensionless imports and tsconfig path aliases; nothing else needs installing. portis held exactly: when it is taken, Studio says so rather than moving the mock. Without one, Studio assigns the key a port fromstudio.mockBasePort(7001 by default). The mock listens there, or on the next free port above it when another process holds it as the mock starts, and the key is assigned another when a mock declares that port. A port the system keeps for itself counts as taken too: Windows keeps blocks of them for Hyper-V, WSL and Docker. After Studio restarts, the mock can get another too. Setportto keep one.- The mock answers each group at its prefix, and — for a source whose
baseURLhas a path, such ashttps://api.example.com/api/v3— under that path too, so a client pointed at the mock with only the host swapped reaches it at/api/v3/usersas one pointed at its bare URL does at/users. seedsets how many records each collection starts with:countfor every group (20 by default), and a number under a group's name for that group alone.autoStartdefaults tofalse. A key set toundefineddeclares no mock, so one can be switched off in place.- The records are generated from each endpoint's response schema, and pass it: the bounds, integer and
multipleOfchecks, string and array lengths, formats (email,url,uuid, ISO dates and times, and the other common ones),regexpatterns and prefixes that a Zod (v4 or v3) or Valibot schema declares all hold, so a typed client validating the responses accepts them. Field names pick realistic values where the schema allows one. - Each running mock is a process of its own that Studio starts: it loads the mocks file with Studio's loader, reusing the transforms Studio keeps, and serves that one mock on the port Studio chose.
- A mock that fails — a definition Studio cannot read, a missing package, a taken port, a crash — is reported in Studio's terminal, and its status in the Mocks view gives the reason on hover or keyboard focus. A running mock whose edited definition cannot be read keeps serving the last one that could, and says so the same way. The mock's own request log appears in Studio's terminal too;
log: "silent"turns it off. - A
courier.mocks.tsthat does not load — a syntax error, an import that cannot be resolved, no default export — leaves the config and its sources working, and the mocks keep serving the definitions that loaded last. Studio's terminal logs why, and a banner above the Mocks view says so until the file loads again. overridesandscenariosare checked againstsource:mocktakes the source's group and endpoint names and each endpoint's response type. Write a scenario withdefineScenario<typeof api>(...)to have it checked the same way; one without the type argument fits every mock. An endpoint declared outside any group is mocked under the collection its path starts with,mock("users", "listUsers"); the types cannot check that name, so a mock under another collection is refused with aMockTargetErrorthat names the right one.scenariosis an object keyed by each scenario's name,{ empty: defineScenario("empty", …) }, which is how Studio and the admin API name them; an array is refused with aScenarioConfigErrorthat spells the object out.- Editing
courier.mocks.ts, or a module it imports, restarts a running mock whose declaration changed, or something that declaration uses — a declaration beside it, an import and every module that import reaches, a statement of the file that declares nothing. The other mocks keep running, with their records: adding a mock does not restart the ones already running. A mocks file whose mocks Studio cannot tell apart — its keys spread in or computed, or a CommonJS file — restarts every running mock on each edit.autoStartapplies when Studio first reads the definition, or when an edit turns it on — not again after you stop the mock. - A mock keeps its records in the project, in
.courier/mocks/— one SQLite database per mock, saved shortly after each request and when the mock stops, and read when it starts — so what an app created is still there after the mock restarts, an edit that changes it included, and after Studio restarts. Nothing is set up by hand: the database and its schema are created on the first start, a database from an earlier Courier is brought up to date as it opens, and records are kept as JSON documents, so an API whose shapes change needs no migration. A save writes, in one transaction, only the records that changed. A database that cannot be read is kept beside the new one as<name>.unreadable-<time>. A collection the database holds nothing for starts from its seeds, and one the mock no longer serves is dropped. Reset store empties the store and seeds it again, and that is kept too.persist: falsestarts the mock from its seeds each time. The database is Node's built-in SQLite, in Node 22.13 and later; elsewhere a mock keeps its records only while it runs, and says so.
Mock only some endpoints, or answer with recordings
A mock need not answer everything. endpoints names the endpoints it answers; every other HTTP call goes to the source's own server at its baseURL, as the app calls it — handy while the backend has all but a few endpoints. fixtures answers with recordings of that server in place of generated data: a call the mock has no answer to yet goes to the server once, its answer is written to a HAR file, and the same call is answered from the file from then on.
// courier.mocks.ts
import { defineMocks, defineMockServer } from "@noverax/courier-mock"
import { api } from "./src/api"
export default defineMocks({
refunds: defineMockServer({ source: api, endpoints: ["users.getById"] }),
demo: defineMockServer({ source: api, fixtures: "./fixtures/api.har" }),
})endpointstakesgroup.method, or the method alone for an endpoint outside any group, and is checked against the source: a name it does not have stops the mock with aMockEndpointsErrorthat lists the names it has. Streams and channels the mock always answers itself. An endpoint left to the server is not mocked at all, so an override or a scenario for it does not apply.- A call passed to the server carries the request's own headers, its credentials included, but none of the hop's (
host,origin,content-length,sec-*and the like). The server's answer, a failure included, comes back with its status, its data and its headers. fixturesis relative tocourier.mocks.ts. The file is a HAR log, the format browsers' developer tools open; commit it to give everyone the same answers. A recording is matched by its endpoint and its variables, and keeps no credentials:authorization,cookieandset-cookieare left out. An override or a scenario on an endpoint answers in place of its recordings. A call with no recording while the server cannot be reached is answered with a 502 that says so; delete the file to record everything again. A file that is not a HAR log of recordings stops the mock with aFixtureFileError.- Studio's mock wizard sets both: Answers takes every endpoint or the ones ticked, and Data generated or recorded, kept in
fixtures/<key>.harbeside the mocks file. The Routes tab tags each route by what answers it,your serverorrecordedamong them, and the mock's log says the same of each call.
A proxy caller pointed at the mock
A mock stands in for the API itself, where a direct caller goes, and also for a Courier proxy, where a proxy caller goes. It serves the proxy's three routes:
| Route | For | As a Courier proxy serves it |
| --- | --- | --- |
| GET/POST /api/request | an HTTP call | the endpoint named by _s, _g and _m in the query; a read's variables in _v, a write's in the JSON or form body |
| GET /api/sse | a stream | the stream's events, the variables in _v |
| /api/ws (WebSocket) | a channel | every channel a caller subscribes to, on one socket, each by its topic |
A mock built from a source refuses at these routes what that API's own proxy refuses — an endpoint it keeps from a page, a GET to anything but a read, or to a read whose variables stay out of the address — with the proxy's status and its body, { "success": false, "message": … }, so a page that works against the mock is not refused once it calls the proxy, and reads a refusal as the proxy writes it.
import { createProxyCaller } from "@noverax/courier/client"
import { routes } from "@noverax/courier/routes"
const mock = "http://localhost:7001"
const api = createProxyCaller(routes.api, {
proxyPath: { http: `${mock}/api/request`, sse: `${mock}/api/sse`, ws: "ws://localhost:7001/api/ws" },
})On /api/ws a subscription goes as it does on a Courier server. The variables are checked against the channel's schema, and a subscription that fails them ends with code 4422. Its topic is keyed as the channel's .topic() says, with a renamed frame first when that differs from the topic asked for, so subscribers who share a key share the channel's broadcasts. Each message is checked against what the channel .send()s, and one that fails is refused with 4422 while the subscription goes on. A channel that is not mocked ends with 4404, naming it and the scenario state. ctx.close() ends that one subscription and leaves the socket's others open. A mock built without a source checks nothing and keys each topic by its variables. Studio's mock logs show each subscription as it opens and ends.
Uploads and large bodies
A mock reads a body as a Courier server does, at every path it serves: JSON — and a body sent with no type, or as plain text, when it is JSON — a form, multipart/form-data or URL-encoded, whose fields reach the handler as a record, a file as the File itself and a field sent more than once as a list, in order, and a file sent as the whole body, which reaches the handler as a Blob of its type. A file's name is kept as it was sent, ../ and all: the mock writes no file, and a generated create keeps each file in its record as its name, type and size. It reads up to 1 MB of JSON and 10 MB of form or upload, as a Courier server does; maxBodyBytes and maxUploadBytes set other limits. A form is parsed by the parser a Courier server uses, as it arrives, its text held to maxBodyBytes and its parts to 1000, and a body that ends short of the length it declared is refused with 413, as a Courier server refuses it.
// courier.mocks.ts
import { defineMocks, defineMockServer } from "@noverax/courier-mock"
import { api } from "./src/api"
export default defineMocks({
api: defineMockServer({ source: api, maxUploadBytes: 50 * 1024 * 1024 }),
})A body over its limit is answered with 413 before it is all read, and the rest is taken off the connection, so a browser still sending it hears the answer; a form that does not parse is answered 400, and so is one whose client stopped sending it. Each is answered { error }, saying why. Studio's mock log shows such a request refused, with its status and the reason, and a file a request sent by its name, type and size.
Slow and failing answers
network makes a mock answer as a slow or unreliable network would, and take uploads as a server with limits does: it adds latency, caps how fast answers are sent and uploads arrive, refuses an upload over a size (413) or holding a file of a type it does not take (415), and fails a share of calls with any HTTP error status, a timeout, a dropped connection or an upload cut off partway, and its stop conditions end a run on their own. Studio's Network tab sets the same conditions on a running mock. See Network conditions.
// courier.mocks.ts
import { defineMocks, defineMockServer } from "@noverax/courier-mock"
import { api } from "./src/api"
export default defineMocks({
api: defineMockServer({
source: api,
network: {
latency: "3g",
errorRate: 0.1,
faultTypes: ["429", "503", "interrupt"],
uploads: { bandwidth: 1500, maxBytes: 5 * 1024 * 1024, accept: ["image/*", ".pdf"] },
},
}),
})Test utilities
import { courier, defineApi, defineGroup } from "@noverax/courier/define"
import { defineFactory } from "@noverax/courier-mock"
import { createMockClient } from "@noverax/courier-mock/testing"
type User = { id: number; name: string; email: string }
const { endpoint } = courier()
const users = defineGroup({ prefix: "users", endpoints: { getAll: endpoint.get("").response<User[]>() } })
const api = defineApi({ baseURL: "https://api.example.com", groups: { users } })
const userFactory = defineFactory<User>({ defaults: { id: 1, name: "Alice", email: "[email protected]" } })
const { client, mock, history } = createMockClient<typeof api>()
mock("users", "getAll").resolves(
userFactory.buildSequence(3, (index, base) => ({ ...base, id: index + 1, name: `User ${index + 1}` })),
)
const all = await client.users.getAll() // three users
history.length // 1Recording a real API
createRecorder calls a real backend from the API's definition and records each response as a fixture — a failed one too. Its client answers as the source's own client does: the data, or an HTTPError with the status and body.
import { createMockClient, createRecorder, replayFixtures } from "@noverax/courier-mock/testing"
const recorder = createRecorder({ source: api, targetUrl: "https://staging.example.com" })
await recorder.client.users.getAll()
const fixtures = recorder.getFixtures() // or recorder.toHar()
const { client: replayed } = createMockClient<typeof api>({ scenario: replayFixtures(fixtures) })- The calls go to each endpoint's own method and path, at
targetUrlor at the source'sbaseURL. To record through a Courier proxy —createCourierServer, or an app with Courier's handler — passproxy: { url, source }: the proxy route's URL and the name the source has there. modeis"record"by default."passthrough"calls the backend and records nothing;"replay"answers from thefixturesgiven, without the network, and rejects a call it has no recording of;"record-missing"replays whatfixtureshas and records the rest.sanitize(data, part)rewrites what is recorded — each call's variables (partis"variables") and each answer's body ("response") — never what the call returns. A recording made with it keeps no query in its URL, and replay passes a call's variables through the same function before looking for their recording; givereplayFixturesandreplayHarthe sanitizer as their third argument for the same reason.Authorization,Proxy-Authorization,CookieandSet-Cookieare never recorded.filternames the endpoints the recorder may call.
Exports
| Entry Point | Description |
|---|---|
| @noverax/courier-mock | defineMocks, defineMockServer, defineFactory, defineScenario, MockHttpError |
| @noverax/courier-mock/testing | createMockClient, createMockStore, createRecorder, replayFixtures |
| @noverax/courier-mock/server | createMockServer — a standalone Hono-based mock server; persist: { file } keeps its store across restarts in an SQLite database it creates and migrates itself |
| @noverax/courier-mock/contract | Contract testing utilities |
| @noverax/courier-mock/managed | runMockWorker — the process Studio starts for each mock it runs |
