scenario check drives pikopod’s own requests. A mode lets your tests meet the failure, but it needs pikopod up in another terminal. The Go package pkg/sandboxtest removes the terminal: one call starts a sandbox from the spec inside the test, in memory, on a random port, and closes it with the test.
retry_storm refuses the first two creates under one idempotency key with 503 and answers the third. A client that retries gets 201 and Verify reports PASSED. A client that gives up after the first 503 gets FAILED, with the summary naming the matcher that never matched, so the test fails for the right reason.
The surface
Nothing from pikopod’s internals appears in these signatures, so the package can stay stable while the engine moves.
From Jest, Vitest or node --test
Copy helpers/jest/pikopod.js into your project. It has no dependencies beyond fetch. It talks to a running pikopod up, or pikopod up --spec examplepay.spec.json in the job before the tests, and takes a fork per test so parallel workers never share state:
fork.fetch(path, init) sends a request to the fork with the credential already set, so createCharge is your own client code pointed at fork.url(). mode, verify, chaos, clearFaults, emit, requests, seed, snapshot, restore and reset mirror the Go surface; PIKOPOD_URL and PIKOPOD_TOKEN are read from the environment.
When several tests share one sandbox and one mode instead of forking, fork.scoped() returns a client that sends X-Pikopod-Scope on every request and verifies only that partition. Inside a Jest test the token is derived from the test name and worker id; pass one explicitly anywhere else:
From pytest or unittest
Copyhelpers/pytest/pikopod.py. Standard library only.
fork.send(method, path, body, headers) returns (status, bytes) with the credential set. The same calls exist in snake case: mode, verify, chaos(**rule), clear_faults, emit, requests, seed, snapshot, restore, reset. scoped(token) returns a client bound to one X-Pikopod-Scope partition; test_scope(request.node.nodeid) derives a token from the pytest node id and the xdist worker.
Both helpers are tested in this repository’s CI against a served example sandbox, and both speak the versioned control plane, /_pikopod/v1/..., documented under Control plane.
One sandbox per test
New builds a fresh in-memory sandbox each time, so parallel tests never share state or modes. Over HTTP, a fork gives the same isolation, which is what the Jest and pytest helpers take per test. When tests must share one sandbox, a scope keeps their fault windows and journals apart without a fork.
What it needs
The spec, as bytes. A documentation page is not accepted here; import it once with the CLI and commit the spec it emits with--emit-spec. See Importing from a docs URL.