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