Stateful Mocking: Simulating APIs That Change Behavior

The problem with memoryless mocks

A basic mock is a pure function: same request, same response, always. That's great for testing a payload's shape, but breaks down when testing real flows — rate limiting, an order that changes status over time, or a resource that only exists after being created. For those, the mock needs state.

httpdrop has three state mechanisms, each fit for a different scenario. None of them require code — everything is configured directly in the Mock Rule.

1. K-V Store: a simple counter across calls

Each endpoint has a persistent key-value space, accessible via storeGet, storeSet, storeIncr, storeDecr and storeReset in the rule's body. Classic example: simulating rate limiting.

// Mock Rule: GET /limited → 200
{
  "callCount": {{storeIncr 'api_calls'}},
  "allowed": "{{#if (lte (storeGet 'api_calls') 3)}}true{{else}}false{{/if}}",
  "message": "{{#if (lte (storeGet 'api_calls') 3)}}Request accepted{{else}}Rate limit exceeded{{/if}}"
}

2. Response Sequences: the same endpoint evolves per call

Configure a list of steps — each request to the same path returns the next one in the list, advancing an index persisted per rule. Perfect for simulating a resource that changes status over time, like an order being processed:

// Mock Rule: GET /orders/123 → Response Sequences
[
  { "status": 200, "body": "{\"status\":\"pending\"}" },
  { "status": 200, "body": "{\"status\":\"processing\"}" },
  { "status": 200, "body": "{\"status\":\"shipped\"}" }
]
// Mode: last (stays on the last step once exhausted)

3. Auto CRUD tables: real state

When the scenario needs actual state — create, list, update, delete — a CRUD table is the right tool instead of manually simulating with store/sequences. A POST /products really persists in the endpoint's SQLite; a GET /products right after reflects what was created — no extra rule needed.

Combining all three

Real scenarios often mix all three: CRUD for the main resource, K-V Store for a login-attempt counter, Response Sequences for simulating an async payment's status evolution. No direct mock server competitor offers all three built in and integrated with real CRUD state at the same time.