← All guides

Mock a REST API for Bun — typed fetch and bun test against a real URL

Bun's in-process mocking story is actually good: bun:test ships jest-style mock() / spyOn() that can stub the global fetch, and MSW works in Bun via msw/node — we verified both before writing this (details in §8). So this guide isn't "your tools are broken." It's about the cases where an in-process interceptor can't help, because what you need is a URL:

• the backend your Bun service consumes doesn't exist yet, and you want to write the client now;
• your retry/backoff/timeout code should be exercised against a server that actually returns 503s slowly, not a stub that answers instantly in-process;
• the same fake data must be visible to your Bun service, the frontend dev's browser, a teammate's machine, and CI — one dataset, not four fixtures drifting apart;
• you want TypeScript to check your client code against the API's actual schema — Bun runs TS natively, and the mock serves its own types.ts (§3).

The boring fix is a hosted mock API. Every snippet below was run verbatim against the live server before publishing (Bun 1.3) — you can paste and run them too.

1. Get an API (10 seconds, no signup)

curl -X POST https://mockbird.mockbird.workers.dev/api/projects \
  -H 'content-type: application/json' -d '{"name":"bun-demo"}'
# → {"id":"abc123","adminKey":"...","baseUrl":"https://mockbird.mockbird.workers.dev/m/abc123", ...}

curl -X POST https://mockbird.mockbird.workers.dev/api/projects/abc123/resources \
  -H 'content-type: application/json' -H 'x-admin-key: YOUR_KEY' \
  -d '{"name":"users","template":"users","seed":50}'

That's 50 realistic users (names, emails, avatars, cities) with full CRUD, filtering, sorting, search and pagination. The snippets below use the public demo project so they run with zero setup.

2. fetch quickstart — real pagination headers

// quickstart.ts
const BASE = "https://mockbird.mockbird.workers.dev/m/demo";

const r = await fetch(`${BASE}/products?page=1&limit=5&sortBy=price&order=desc`);
if (!r.ok) throw new Error(`HTTP ${r.status}`);
const products = await r.json();
const total = Number(r.headers.get("x-total-count"));   // real header, not a fixture
console.log(`${total} products total; page of ${products.length}`);

bun run quickstart.ts

Output when we ran it: 30 products total; page of 5. No tsconfig, no build step — Bun runs the .ts file directly. Exact-match filters (?category=tools), range operators (?price_gte=100), substring match (?name_like=river) and full-text ?q= all compose — see the parameter reference.

3. Type-check your client against the live schema

Mockbird generates TypeScript interfaces for your schema at /m/<project>/types.ts. Pull the file once and import it — since Bun executes TypeScript natively, there's no codegen pipeline to configure:

curl -o types.ts https://mockbird.mockbird.workers.dev/m/demo/types.ts

// typed.ts
import type { Product } from "./types.ts";

const r = await fetch("https://mockbird.mockbird.workers.dev/m/demo/products?limit=1");
const [p]: Product[] = await r.json();
console.log(p.name, p.price);   // p is fully typed: name, price, category, inStock, rating…

bun run typed.ts                                   # runs as-is
bunx tsc --noEmit --strict --target es2022 --module esnext \
  --moduleResolution bundler --allowImportingTsExtensions typed.ts   # type-checks it

Bun itself doesn't type-check (it strips types), so the bunx tsc --noEmit line is the enforcement step for CI. The checking is real — when we fed it const p: Product = { id: 1, name: "x" }, tsc failed with TS2740: Type '…' is missing the following properties from type 'Product': description, price, image, category, and 2 more. Change your schema in the dashboard, re-curl the file, and your client code is re-checked against the new contract. (Prefer runtime validation? ?format=zod serves Zod schemas instead.)

4. Writes are real

const created = await (await fetch(`${BASE}/products`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ name: "Test Widget", price: 9.99 }),
})).json();                                              // 201 + the stored record

const back = await (await fetch(`${BASE}/products/${created.id}`)).json();
console.assert(back.name === "Test Widget");             // it persisted
await fetch(`${BASE}/products/${created.id}`, { method: "DELETE" });

PUT/PATCH/DELETE behave like a real backend — after the DELETE, a GET for that id really 404s (we checked). This is the part JSONPlaceholder, FakeStoreAPI and DummyJSON fake — details with receipts in their respective guides. Add ?mock_validate=1 to get real 422s with per-field errors when the body doesn't match the schema.

5. Sad paths: force any status, hit a real timeout

// any status code on demand
const err = await fetch(`${BASE}/products?mock_status=503`);
console.log("forced status:", err.status);               // 503

// a genuinely slow response vs your client timeout
try {
  await fetch(`${BASE}/products?mock_delay=3000`, { signal: AbortSignal.timeout(1000) });
} catch (e) {
  console.log("timeout branch actually ran:", (e as Error).name);   // "TimeoutError"
}

That second one matters: an in-process stub answers instantly, so your AbortSignal.timeout() handling is never truly exercised. Here the server really holds the response for 3 seconds and the abort really fires — we saw TimeoutError, live, in Bun 1.3.

6. Exercise real retry logic with injected chaos

Bun has no retry helper in the standard library, but bun add p-retry took 135 ms on our machine. Point it at an endpoint where ~half the requests fail with a random 5xx/429 and watch it earn its keep:

import pRetry from "p-retry";

const BASE = "https://mockbird.mockbird.workers.dev/m/demo";
let absorbed = 0;

async function getProducts() {
  const r = await fetch(`${BASE}/products?mock_chaos=0.5&limit=1`);
  if (!r.ok) {
    absorbed++;
    throw new Error(`HTTP ${r.status}`);   // make injected 5xx/429 throw so pRetry kicks in
  }
  return r.json();
}

for (let i = 0; i < 5; i++) {
  await pRetry(getProducts, { retries: 6, minTimeout: 200, factor: 2, randomize: true });
  console.log(i, 200);
}
console.log(`${absorbed} injected failures absorbed by p-retry`);

Our run: five 200s, 2 injected failures absorbed by p-retry. mock_chaos=0.5 fails that fraction of requests with a random status from {500, 502, 503, 504, 429}; injected failures carry an x-mockbird-chaos: injected header, and chaos-failed writes are not applied — so it's safe to point retrying write logic at it too. (With chaos at 0.5 and 6 retries there's a small give-up branch per call — if p-retry surfaces the error, that's the mock doing its job.) For deterministic 429 testing (fixed window, real Retry-After and x-ratelimit-* headers), use ?mock_ratelimit=N.

7. bun test: pin each test to a frozen snapshot

Shared mutable test data is how suites go flaky. Mockbird lets you save named snapshots of a project's entire dataset, then answer any GET from a snapshot — read-only, live data untouched — by sending one header. Set the scenarios up once:

ADMIN='x-admin-key: YOUR_KEY'
P=https://mockbird.mockbird.workers.dev/api/projects/abc123

curl -X POST $P/snapshots -H "$ADMIN" -H 'content-type: application/json' -d '{"name":"baseline"}'
curl -X POST $P/resources/users -H "$ADMIN" -H 'content-type: application/json' -d '{"seed":0}'   # wipe
curl -X POST $P/snapshots -H "$ADMIN" -H 'content-type: application/json' -d '{"name":"empty"}'
curl -X POST $P/snapshots/baseline/restore -H "$ADMIN"    # put live data back

Then each test pins the scenario it wants — with Bun's jest-compatible built-in runner, no extra dev-dependency. No beforeEach resets, no ordering constraints, and parallel tests can't race each other because nobody mutates anything:

// api.test.ts — run with: bun test
import { test, expect } from "bun:test";

const BASE = "https://mockbird.mockbird.workers.dev/m/abc123";

function api(snapshot = "baseline") {
  return (path: string) =>
    fetch(`${BASE}${path}`, { headers: { "X-Mockbird-Snapshot": snapshot } });
}

test("user list (baseline: always 5)", async () => {
  const r = await api()("/users");
  expect(await r.json()).toHaveLength(5);
});

test("empty state", async () => {
  const r = await api("empty")("/users");
  expect(await r.json()).toEqual([]);
  expect(r.headers.get("x-total-count")).toBe("0");
});

We ran exactly this file before publishing: 2 pass, 0 fail — Ran 2 tests across 1 file. [266.00ms] — two real network round-trips, still comfortably fast. Want to try pinning with zero setup? The public demo ships with built-in empty and edge-cases snapshots (100-char names, unicode, price 0, HTML-ish strings):

bun -e 'console.log(await (await fetch("https://mockbird.mockbird.workers.dev/m/demo/products?mock_snapshot=empty")).json())'
// → []

The same trick scales per-scenario — edge-cases, bug-repro-1234 — see the deterministic test data guide.

8. Honest comparison

In-process mocks are the right call for millisecond-fast pure unit tests, and Bun's options genuinely work — we tested them:

Use both: keep bun:test mocks for unit tests that must run offline, and point integration tests, scripts, teaching materials and not-yet-built-backend work at a hosted URL.

9. Ship day

Mockbird follows plain REST conventions, so switching to the real backend is one base-URL change — and Bun auto-loads .env, so const BASE = Bun.env.API_URL needs no dotenv package (we verified the swap works with the mock URL in .env). Hand your backend team the live contract while they build it: https://mockbird.mockbird.workers.dev/m/abc123/openapi.json, a Postman collection, or the same types.ts your Bun code already imports — one schema, checked at both ends.