Latency and timeouts

Make responses slow, or make them never arrive. Latency is how long every request takes; a timeout holds a request and then drops it. With virtual time, the waits are spent on the mock clock and cost no test time.

#Interface

A duration is milliseconds or a string: "250ms", "2s", "15m", "1h", "3d".

#Admin page

Open http://localhost:8787/__admin/ui#manual for manual UI testing. Choose a method, exact path and/or operation ID, then arm Delay next request, Timeout next request, or Fail next request (503). The wait defaults to 3,000 milliseconds and the count to one, so the next retry can recover. Blank match fields target every vendor request in the current namespace; background requests can consume a rule. Multiple filled fields must all match.

Enable Use real waits to hold the response while you inspect your app. Virtual time finishes delays immediately. Each action adds a fault rule; existing rules and baseline latency still apply. The Armed rules table shows remaining counts and lets you remove individual rules without resetting state. Removing a rule affects future requests, not an existing wait.

To check loading, errors and retry manually:

1. Target the app's request and click Delay next request, then trigger the action in the app. Inspect its loading indicator while the response is held.
2. Click Timeout next request and trigger the action again. After the timeout, inspect the error message and Retry button. Timeouts drop the connection; Bun's server returns 500 instead.
3. Click Retry in the app without arming another fault. Watch the live journal on the same screen: the attempt count increases and another row records the request and its outcome. Status 0 records a dropped connection. Entries appear after completion or failure, not while pending.

The journal uses the same request filters, refreshes every 1.5 seconds, and can be paused. Counts cover the latest 1,000 matching retained requests. Clear the journal before a fresh run if you want an empty baseline. Repeated requests demonstrate traffic reaching the emulator; polling or another caller can also increase counts, so correlate them with the action in your app.

For persistent latency, open http://localhost:8787/__admin/ui#latency.

For a manual timeout, use Manual controls. You can also send x-mockingbird-timeout on the request, or set timeout on a fault. Virtual time is the switch on Clock.

#Three ways to wait

They add up: a request waits its latency, then its header's delay, then the delay of each fault rule that fires.

#Admin API

#PUT /__admin/latency

Set the namespace's baseline response time.

curl -X PUT localhost:8787/__admin/latency \
  -d '{"delay": "40ms", "jitter": "10ms", "operations": {"CreateCharge": {"delay": "250ms"}}}'

{
  "delayMs": 40,
  "jitterMs": 10,
  "operations": { "CreateCharge": { "delayMs": 250, "jitterMs": 0 } }
}

#GET /__admin/latency

The same body.

curl localhost:8787/__admin/latency

#DELETE /__admin/latency

Remove it.

curl -X DELETE localhost:8787/__admin/latency

{ "delayMs": 0, "jitterMs": 0, "operations": {} }

#Timeouts

A timeout never answers: it holds the request for a duration, then drops the connection. An in-process fetch rejects with a TypeError; a served emulator destroys the socket.

# The next CreateCharge hangs for 30 seconds and then dies.
curl -X POST localhost:8787/__admin/faults -d '{"operationId": "CreateCharge", "timeout": "30s", "count": 1}'

# This request only.
curl -X POST localhost:8787/v1/charges -H 'x-mockingbird-timeout: 30s' \
  -H 'authorization: Bearer sk_test_mockingbird'

The timeout preset is the same thing by name. A held request ends as soon as the caller gives up.

#Virtual time

By default a wait is real: the emulator holds the response for that long on the wall clock, which is what trips a client's own timeout.

With virtualTime, a wait is spent on the mock clock instead. The request returns at once, the clock has moved forward by the wait, and the journal records it exactly.

curl -X PUT localhost:8787/__admin/controls -d '{"virtualTime": true}'

Turn it off with {"virtualTime": false}, or per namespace with the x-mockingbird-virtual-time header.

#Request headers

#At boot

{
  "latency": { "delay": "40ms", "jitter": "10ms", "operations": { "CreateCharge": "250ms" } },
  "virtualTime": true
}

npx mockingbird-stripe serve --latency 40ms --jitter 10ms --virtual-time

"latency": "40ms" is short for {"delay": "40ms"}.

#In process

runtime.latency.set("default", { delayMs: 40, jitterMs: 10, operations: {} })
runtime.latency.get("default")   // { delayMs, jitterMs, operations }
runtime.latency.clear("default")
runtime.configure({ virtualTime: true, latency: "40ms" })
runtime.headers({ delay: "250ms", timeout: "30s" })

#Rules

• Jitter is seeded, from a stream of its own per namespace. The same seed gives the same waits, and adding latency never shifts which requests a rate fault hits.
• Latency applies to vendor requests, not to /__admin.
• The journal records the wait as delayMs on each entry.
• The Node server and the CLI destroy the socket for a timeout. Bun.serve cannot close a connection from a handler, so the Bun adapter answers 500.

#Errors

#Related

• Faults for delay, jitter and timeout on the requests a rule matches.
• Clock, which virtual time moves.