stubfetch

Deterministic, in-process fake HTTP APIs for testing agents and tools. Swap real network calls for canned GitHub, Stripe, Postgres-shaped data, OpenAI / Anthropic-style LLM JSON, S3-like objects, Slack Web API responses—while recording traffic, exporting JSON / Markdown / HAR, running eval scenarios, and optionally injecting chaos (latency, random failures).

Same ideas in TypeScript (npm) and Python (PyPI / local install).

---

Install

JavaScript / TypeScript (npm)

npm install stubfetch

Requires Node.js ≥ 18. No runtime npm dependencies.

Python

pip install stubfetch

From a clone (editable):

pip install -e ./python

Requires Python ≥ 3.10.

---

Quick start

TypeScript

import { GhostEnv, github, exportRecordingJSON } from "stubfetch";

const env = new GhostEnv({
  seed: 42,
  providers: [github({ issues: [{ repo: "acme/api", title: "Bug" }] })],
});

const res = await env.fetch("https://api.github.com/repos/acme/api/issues");
console.log(await res.json());
console.log(exportRecordingJSON(env.calls()));

Python

from stubfetch import GhostEnv, github, export_recording_json

env = GhostEnv(
    {"seed": 1, "providers": [github({"issues": [{"repo": "acme/api", "title": "Bug"}]})]}
)
status, text = env.fetch("https://api.github.com/repos/acme/api/issues")
assert status == 200
print(export_recording_json(env.calls()))

---

Features

Area	What you get
Presets	GitHub issues, Stripe customers, Postgres db().query(), OpenAI chat, Anthropic messages, S3 GET/list, Slack auth.test / chat.postMessage
GhostEnv.fetch	Same shape as globalThis.fetch; routes to the first matching provider
Recording	calls(), wasCalled(), exportRecordingJSON / Markdown / HAR
Eval	runEval + defineScenario for scripted agent tests
Replay	ReplayFixture replays canned responses in order
Chaos	chaos: { minLatencyMs, failureRate } on config

---

Documentation

Hosted on slaps.dev:

Doc	Contents
Overview	Product summary and doc index
Getting started	Providers, fetch, recording
Use cases	Agents, agentpad, eval patterns
Presets	URLs, config shapes, matching rules
API reference	GhostEnv, Provider, eval, replay, exports
Testing & chaos	runEval, chaos options, failure recording
Python notes	Node vs Python differences

---

License

Apache-2.0