DEV Community: ToolboxMApp

How to Test Retry Logic Without a Backend

ToolboxMApp — Sun, 27 Sep 2026 10:20:28 +0000

Originally published on the ScenarioMock blog.

You've written the retry logic. Exponential backoff, three attempts, then give up and show the user an error. It looks right.

How do you know it works?

Against a real staging backend, you'd have to break the thing on purpose. Against a mock, the endpoint cheerfully returns 200 every single time, and the retry branch never executes. The code ships untested, and the first time it runs for real is in production, during an outage.

Why static mocks can't test retry logic

A static mock maps one request shape to one response. Send the same request twice, get the same answer twice. That is exactly what makes it useless here.

Retry logic isn't a property of a single request. It's a property of a sequence of them. The behaviour you care about — does it back off, does it stop at the limit, does it recover cleanly when the endpoint comes back — only exists across multiple calls.

You can, of course, hard-code the fixture to return 503. Now your retry loop runs, exhausts its attempts, and surfaces an error. That tests the failure path. What it doesn't test is the recovery path, and that's where the interesting bugs live: state that never gets cleared, a loading spinner that stays up after a successful retry, a duplicate request fired because the first attempt wasn't properly cancelled.

To catch those, the endpoint has to fail and then succeed.

A Sequence scenario, step by step

A Sequence scenario in ScenarioMock keys off one thing: how many times it has been evaluated. You give it an ordered list of steps, each with a match_count and a response. The first step whose count matches wins.

match_count takes an exact number, or one of >=N, <=N, >N, <N.

So "fail twice, then succeed forever" is two steps:

Step	match_count	Response
1	`<=2`	`503 Service Unavailable`
2	`>=3`	`200 Payment Success`

That's the entire configuration. No code, no conditional branches, no fixture juggling.

Each response can also carry a delay_ms, which is what makes this useful for timeout testing too — a step that waits three seconds before returning 504 will exercise your client's timeout handling in a way a fast error response never will.

Try it right now

There's a public demo project you can call without signing up. Mock endpoints don't require authentication.

HOST=https://demo-mock--ecommerce-api.scenariomock.com

curl -s -X POST $HOST/api/payment \
  -H "Content-Type: application/json" \
  -d '{"amount":9800,"currency":"JPY","card":"4242424242424242"}'

The first two calls return 503:

{"error":"Service temporarily unavailable","retryAfter":1,"requestId":"req_f3a2b91c"}

The third returns 200:

{"status":"success","transactionId":"txn_8f3a2b91","amount":9800,"currency":"JPY","paidAt":"2026-06-21T10:00:00Z"}

Point your retry client at that URL instead of curl and you have a real test of the failure-then-recovery path.

One caveat about this particular demo. Its counter is set to global scope and the counter clears 300 seconds after the first request, so you're sharing it with everyone else reading this page. If your first call comes back 200, someone else already used up the two failing calls shortly before you did — wait a few minutes and start again.

In your own project you'd use per_ip scope instead, which gives each caller an independent counter. That's the setting you want for anything other than a public demo.

There's a second Sequence endpoint on the same demo that models a flaky third-party API — first call times out after a three-second delay, second returns 500, third onward succeeds:

curl -s -X POST $HOST/api/shipping/quote \
  -H "Content-Type: application/json" \
  -d '{"zip":"100-0001","weight_kg":2.5}'

Building the same thing in your own project

Four steps:

Create a project. The slug becomes part of your mock's subdomain: https://{your-domain}--{slug}.scenariomock.com.
Create an endpoint — method and path, for example POST /api/payment.
Add a Sequence scenario. Define two steps: <=2 returning your error response, >=3 returning success.
Set the scope to per_ip so concurrent testers don't share a counter.

To run the sequence again, reset the counter from the endpoint screen. You can also set reset_after_seconds so it clears on its own.

Two things that will trip you up

A request that matches no scenario returns 200, not an error.

If a request matches an endpoint but no scenario produces a response, you get:

{"message":"No scenario matched"}

with status 200. This surprises people who expect a 404 or a 500.

The usual cause is steps that don't cover every count. If you define match_count: 1 and match_count: 2 and nothing else, the third request falls through every step, and you get the message above instead of the success response you were expecting. Using >=N on the final step avoids this.

reset_after_seconds is a window, not an idle timeout.

The timer starts on the first request and is not extended by subsequent ones. Setting it to 300 means the counter clears five minutes after the sequence began, regardless of how many calls happened in between. If you're expecting "clears after five minutes of inactivity", you'll get different behaviour than you planned.

Worth knowing as well: counters are tracked per scenario, not per endpoint. Two Sequence scenarios on the same endpoint each count their own evaluations independently.

The demo above is part of ScenarioMock, a hosted mock API server I built.
Free tier is enough to try this out — https://scenariomock.com

Curious how other people handle this. Are you testing retry paths at all,
or is that branch just shipping untested?

I built a Stateful Mock API server because existing tools only return fixed responses

ToolboxMApp — Wed, 15 Jul 2026 07:27:26 +0000

The problem with existing mock tools

Every time I needed to test an API client, I ran into the same wall.

I'd set up Mockoon or WireMock, configure my endpoints, and then try to test a
realistic flow:

POST /users  {"name": "Yoshi"}
# → 201 {"id": "abc123", "name": "Yoshi"}  ✅

GET /users/abc123
# → 200 {"id": "abc123", "name": "Yoshi"}  ❌ returns the fixed mock, not the created user

The second request always returns the preconfigured static response — not the
resource that was just created. Because that's how mock tools work: they replay
fixed responses, they don't maintain state.

To test a real CRUD flow, I had two options:

Write custom server code every time
Stand up an actual backend

Neither felt right for "I just want to test my API client."

So I built ScenarioMock.

What ScenarioMock does

Stateful Mock

Resources created via POST are stored in Redis and can be retrieved, updated,
and deleted — just like a real database-backed API.

# Create
curl -X POST https://yourname--my-api.scenariomock.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Yoshi"}'
# → {"id": "abc123", "name": "Yoshi"}

# Retrieve — returns the created resource, not a fixed response
curl https://yourname--my-api.scenariomock.com/users/abc123
# → {"id": "abc123", "name": "Yoshi"}

# Update
curl -X PUT https://yourname--my-api.scenariomock.com/users/abc123 \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'
# → {"id": "abc123", "name": "Yoshi", "role": "admin"}

# Delete
curl -X DELETE https://yourname--my-api.scenariomock.com/users/abc123
# → 204

# After delete → 404
curl https://yourname--my-api.scenariomock.com/users/abc123
# → 404

All of this is configured through a GUI — no code required.

Each project gets its own subdomain in the form {your-domain}--{project-slug}.scenariomock.com.

Scenario Engine

Three scenario types for dynamic behavior:

Static — Always return the same response. The simplest case.

Sequence — Return different responses based on request count:

Request #1 → 200 {"ok": true}
Request #2 → 429 {"error": "rate limited"}
Request #3+ → 200 {"ok": true}

Useful for testing retry logic, rate limit handling, or transient error recovery.

Conditional — Branch based on request content:

If Authorization header is missing → 401
Otherwise → 200

If body.email matches .*@test\.com$ → 403
Otherwise → 200

Conditions can reference headers, query params, body fields (dot notation), or
path parameters. Logic operators all / any / not can be nested.

Shared URL

Make a project public and share the URL. Anyone can:

View the endpoint list
Send test requests directly in the browser
See real-time request logs via WebSocket

No account required to view or test. Perfect for sharing a mock with a client
or a teammate who just needs to hit an endpoint.

Here's a live example — a mock e-commerce API with stateful CRUD and a couple
of scenarios wired up — you can try right now, no signup required:

https://scenariomock.com/shared/demo-mock--ecommerce-api

Technical design decisions

Single Fastify process, hostname-based routing

ScenarioMock runs as a single Node.js process. The host header determines
which handler runs:

function isAppHost(hostname: string): boolean {
  return hostname.startsWith('app.') || hostname === 'localhost';
}

// yourname--my-api.scenariomock.com → { domain: 'yourname', slug: 'my-api' }
function parseSubdomain(hostname: string): { domain: string; slug: string } | null {
  const match = hostname.split(':')[0].match(/^([a-z0-9][a-z0-9-]*)\.(.+)$/);
  if (!match || ['app', 'www'].includes(match[1])) return null;
  const [domain, slug] = match[1].split('--');
  return domain && slug ? { domain, slug } : null;
}

app.scenariomock.com → Management API (auth required)
yourname--my-api.scenariomock.com → Mock handler (no auth, catch-all routes)

For local development, *.lvh.me resolves to 127.0.0.1 via a public DNS
service, so subdomain routing works without editing /etc/hosts.

Pluggable scenario handlers

Each scenario type implements a ScenarioHandler interface:

interface ScenarioHandler<TConfig = unknown> {
  type: string;
  configSchema: z.ZodType<TConfig>;
  evaluate(
    config: TConfig,
    ctx: ScenarioContext,
    state: StateStore,
    responseLoader: ResponseLoader,
  ): Promise<ScenarioResult | null>; // null = skip to next scenario
}

The engine iterates through enabled scenarios in priority order. The first
non-null result wins. Adding a new scenario type means implementing this
interface — no changes to the engine itself.

Redis for scenario state

The stateful_collection scenario stores data in Redis Hash:

key:   collection:{projectId}:{stateKey}
type:  Hash
field: {itemId}
value: JSON string
TTL:   configurable (default 24h)

Using Redis Hash gives us O(1) HGET/HSET operations and native TTL support.
The sequential ID counter lives alongside it:

key:   collection:{projectId}:{stateKey}:seq
type:  String (integer)
ops:   INCR

For Sequence scenarios, the request counter is:

key:   seq:{endpointId}:{scenarioId}:{scopeKey}
type:  String (integer)
ops:   INCR, EXPIRE

scopeKey can be global, the caller's IP, or a specific header value — so
you can simulate per-user rate limits. Each Sequence scenario keeps its own
counter.

Real-time log streaming

Every Mock request is logged to PostgreSQL and also published to a Redis
Pub/Sub channel:

channel: project:{projectId}:logs
payload: JSON (same shape as request_logs table)

The WebSocket handler subscribes and forwards messages to connected browsers.
Authorization headers and cookies are redacted server-side before logging.

Bugs I hit along the way

Zod union order matters

I had this in the conditional scenario's predicate schema:

const predicateSchema = z.union([
  z.object({ equals: z.unknown() }),   // ← first
  z.object({ missing: z.literal(true) }),
  // ...
]);

z.unknown() accepts undefined, so { missing: true } was parsed as
{ equals: undefined } — which JSON.stringify turns into {}. The evaluator
saw an empty object, matched nothing, and the condition was always false.

Fix: put the most constrained types first, z.unknown() last.

Vite proxy + DELETE + Content-Type = 500

My apiRequest wrapper always set Content-Type: application/json, even for
requests without a body. Through Vite's dev proxy, this caused DELETE requests
to be sent as chunked transfer encoding. Fastify saw Content-Type: application/json
and tried to parse the empty body — SyntaxError → 500.

Fix: only set Content-Type when options.body !== undefined.

ZodError wasn't caught by the error handler

Routes used schema.parse(req.body) which throws ZodError on invalid input.
The global error handler only checked for AppError and Fastify's built-in
error.validation — ZodError fell through to the 500 handler.

Fix: add instanceof ZodError check before the generic 500 branch:

if (error instanceof ZodError) {
  return reply.code(400).send({
    error: { code: 'validation_error', message: 'Validation failed', details: error.errors },
  });
}

Stack summary

Layer	Technology
Runtime	Node.js 20 + TypeScript strict
HTTP framework	Fastify 5
Database	PostgreSQL 16 via Kysely
Cache / state	Redis 7 via ioredis
Validation	Zod
Frontend	React 18 + Vite + Tailwind + shadcn/ui
Auth	JWT (HS256) via @fastify/jwt
Payments	Stripe Checkout + Webhooks
Backend hosting	Fly.io (Singapore region)
Frontend hosting	Cloudflare Pages
DB hosting	Neon (serverless Postgres)
Redis hosting	Upstash (serverless Redis)
Error tracking	Sentry

Monthly cost at launch (July 2026): ~$3 (domain only — everything else was
within free tiers).

Android companion app

I also build Android apps, and I wanted a way to test ScenarioMock endpoints
from my phone. My existing app fits perfectly:

API Tester – REST & JSON Client

Build the mock on ScenarioMock, fire requests from the Android app. A complete
API testing workflow without running any local server.

Try it

https://scenariomock.com — Free plan, no credit card required.

I'd love to hear what you think. Which scenario type would you use most?
What's missing? Drop a comment below 👇

If you want to see this in practice, I wrote up how to use it for
testing retry logic.