Scenarios and state¶
Stubs are stateless by default: the same request gets the same answer. Scenarios add state machines, so a mock can behave like the real service over a sequence of calls: an order that is created, paid and shipped, a provider that fails twice and then succeeds, a token that can be used once. The key-value store holds values that tests set and plugins use.
- Scenario rules
- Templated scenario names
- Example: order lifecycle
- Example: fail twice, then succeed
- Expiry
- Concurrency and replicas
- Inspecting, setting and resetting state
- Key-value store
- Limits
Scenario rules¶
A stub joins a scenario with the scenario block:
{
"scenario": {"name": "checkout", "requiredState": "Started", "newState": "PAID", "ttlSeconds": 3600},
"request": {"method": "POST", "urlPath": "/checkout"},
"response": {"status": 200, "jsonBody": {"status": "PAID"}}
}
| Field | Default | Meaning |
|---|---|---|
name |
required | Scenario name; a template, so it can depend on the request. |
requiredState |
none | The stub matches only while the scenario is in this state. Without it the stub matches in every state. |
newState |
none | After the stub matched, the scenario moves to this state. Without it the state does not change. |
ttlSeconds |
604800 (7 days) |
How long the state set by this stub is kept, 1 to 31536000 seconds. Only used with newState. |
Every scenario starts in the state Started. A scenario that was never touched, was reset or has expired is
in Started.
Matching works as usual (see Request matching): stubs are tried in priority order; a stub
whose requiredState differs from the current state is skipped and the next candidate is tried. So give a
"fallback" stub without scenario a higher priority number if it should answer when no state-specific stub
applies.
Templates in the response, headers, callbacks and messages see the scenario as state:
| Variable | Value |
|---|---|
state.scenario |
the rendered scenario name, for example order-A-1 |
state.current |
the state before this request's transition |
Templated scenario names¶
Because name is a template, one set of stubs drives a separate state machine per order, user or message:
{"scenario": {"name": "order-{{request.pathParams.id}}", "requiredState": "CREATED", "newState": "PAID"}}
Order A-1 and order B-2 then have independent states (order-A-1, order-B-2). Anything in the template
context can be used: {{request.json.orderId}}, {{request.headers.x-client-id}}, {{request.query.session}}.
The rendered name may be up to 512 bytes; a longer name makes the request fail with 500
(stub evaluation failed).
Example: order lifecycle¶
Six stubs, imported together under the tag orders (replaceTag replaces earlier versions of the same set):
curl -s -X POST localhost:9090/__admin/stubs/import \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' -d '{
"replaceTag": "orders",
"stubs": [
{"name": "create order", "request": {"method": "POST", "urlPath": "/orders"},
"scenario": {"name": "order-{{request.json.id}}", "requiredState": "Started", "newState": "CREATED", "ttlSeconds": 3600},
"response": {"status": 201, "jsonBody": {"id": "{{request.json.id}}", "status": "CREATED"}}},
{"name": "order is created", "request": {"method": "GET", "urlPathTemplate": "/orders/{id}"},
"scenario": {"name": "order-{{request.pathParams.id}}", "requiredState": "CREATED"},
"response": {"status": 200, "jsonBody": {"id": "{{request.pathParams.id}}", "status": "CREATED"}}},
{"name": "pay order", "request": {"method": "POST", "urlPathTemplate": "/orders/{id}/pay"},
"scenario": {"name": "order-{{request.pathParams.id}}", "requiredState": "CREATED", "newState": "PAID", "ttlSeconds": 3600},
"response": {"status": 200, "jsonBody": {"id": "{{request.pathParams.id}}", "status": "PAID", "previous": "{{state.current}}"}}},
{"name": "order is paid", "request": {"method": "GET", "urlPathTemplate": "/orders/{id}"},
"scenario": {"name": "order-{{request.pathParams.id}}", "requiredState": "PAID"},
"response": {"status": 200, "jsonBody": {"id": "{{request.pathParams.id}}", "status": "PAID"}}},
{"name": "pay twice", "priority": 6, "request": {"method": "POST", "urlPathTemplate": "/orders/{id}/pay"},
"response": {"status": 409, "jsonBody": {"error": "order {{request.pathParams.id}} cannot be paid"}}},
{"name": "unknown order", "priority": 9, "request": {"method": "GET", "urlPathTemplate": "/orders/{id}"},
"response": {"status": 404, "jsonBody": {"error": "order {{request.pathParams.id}} not found"}}}
]}'
The flow (real responses):
GET /orders/A-1 -> {"error":"order A-1 not found"}
POST /orders {"id":"A-1"} -> {"id":"A-1","status":"CREATED"}
GET /orders/A-1 -> {"id":"A-1","status":"CREATED"}
POST /orders/A-1/pay -> {"id":"A-1","status":"PAID","previous":"CREATED"}
POST /orders/A-1/pay -> {"error":"order A-1 cannot be paid"}
GET /orders/A-1 -> {"id":"A-1","status":"PAID"}
GET /orders/B-2 -> {"error":"order B-2 not found"}
The pay twice and unknown order stubs have no scenario and a higher priority number, so they answer only when
no state-specific stub matched. Add callbacks to pay order to send the payment webhook, or
Kafka messages to publish an OrderPaid event.
Example: fail twice, then succeed¶
Useful for testing client retries. The scenario is per client, taken from a header:
{"replaceTag": "flaky-sms", "stubs": [
{"name": "first attempt fails", "request": {"method": "POST", "urlPath": "/sms"},
"scenario": {"name": "sms-{{request.headers.x-client-id}}", "requiredState": "Started", "newState": "failed-once", "ttlSeconds": 60},
"response": {"status": 503, "jsonBody": {"error": "try again"}}},
{"name": "second attempt fails", "request": {"method": "POST", "urlPath": "/sms"},
"scenario": {"name": "sms-{{request.headers.x-client-id}}", "requiredState": "failed-once", "newState": "failed-twice", "ttlSeconds": 60},
"response": {"status": 503, "jsonBody": {"error": "try again"}}},
{"name": "then it works", "request": {"method": "POST", "urlPath": "/sms"},
"scenario": {"name": "sms-{{request.headers.x-client-id}}", "requiredState": "failed-twice"},
"response": {"status": 202, "jsonBody": {"accepted": true, "scenario": "{{state.scenario}}"}}}
]}
POST /sms (x-client-id: c1) -> 503 {"error":"try again"}
POST /sms (x-client-id: c1) -> 503 {"error":"try again"}
POST /sms (x-client-id: c1) -> 202 {"accepted":true,"scenario":"sms-c1"}
POST /sms (x-client-id: c1) -> 202 {"accepted":true,"scenario":"sms-c1"}
POST /sms (x-client-id: c2) -> 503 {"error":"try again"}
Sixty seconds after the last transition the state of sms-c1 expires and the cycle starts again.
Expiry¶
Each transition stores the new state with the ttlSeconds of the stub that made it (default 7 days). When the
time passes, the state disappears and the scenario is back in Started. A stub without newState does not
extend the expiry. States set through PUT /__admin/scenarios/{name} do not expire.
Use short TTLs for per-request scenarios (one per order or message) so state does not accumulate, and the default or longer for long-running test environments.
Concurrency and replicas¶
Scenario states live in Valkey (in memory mode: in the process), so every replica sees the same state.
Transitions use compare-and-set: of two concurrent requests that both see CREATED and want to move to PAID,
exactly one wins. The other is matched again against the new state (and then gets, for example, the pay twice
answer). If the state keeps changing under a request, FastMock gives up after 8 rounds and answers 500.
Inspecting, setting and resetting state¶
| Call | Role | Effect |
|---|---|---|
GET /__admin/scenarios |
viewer | Lists scenarios that have a stored state (scenarios never touched are implicitly Started and not listed): {"scenarios":[{"name":"order-A-1","state":"PAID"}]} (up to 10,000). |
PUT /__admin/scenarios/{name} with {"state": "..."} |
editor | Sets a state (no expiry). Name and state are limited to 512 bytes; percent-encode special characters in the name. Returns 204. |
DELETE /__admin/scenarios |
editor | Resets every scenario to Started. Returns {"reset": n}. |
POST /__admin/reset |
admin | Clears the journal, callbacks and all scenario states. |
curl -s localhost:9090/__admin/scenarios -H "Authorization: Bearer $FASTMOCK_TOKEN"
curl -s -X PUT localhost:9090/__admin/scenarios/order-A-1 \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' -d '{"state":"CREATED"}'
curl -s -X DELETE localhost:9090/__admin/scenarios -H "Authorization: Bearer $FASTMOCK_TOKEN"
Setting a state is the fastest way to start a test in the middle of a flow ("an order that is already paid")
without replaying the requests that lead there. With the Java client: setScenarioState(name, state) and
resetScenarios() (Java client).
Key-value store¶
A shared string store with optional expiry, kept next to the scenario states. Tests use it to hand data to plugins or to keep fixtures that several test processes share.
| Call | Role | Effect |
|---|---|---|
PUT /__admin/kv/{key} with {"value": "...", "ttlSeconds": 600} |
editor | Stores a string value; ttlSeconds (1 to 31536000) is optional. Returns 204. |
GET /__admin/kv/{key} |
viewer | {"key": "...", "value": "..."}, or 404 {"error":"key not found","details":[]}. |
DELETE /__admin/kv/{key} |
editor | 204, or 404 when the key did not exist. |
curl -s -X PUT localhost:9090/__admin/kv/feature-flags -H "Authorization: Bearer $FASTMOCK_TOKEN" \
-H 'content-type: application/json' -d '{"value": "{\"newCheckout\": true}", "ttlSeconds": 600}'
curl -s localhost:9090/__admin/kv/feature-flags -H "Authorization: Bearer $FASTMOCK_TOKEN"
Values are strings; store JSON as a string as above. Keys are 1 to 512 bytes and values up to 1 MiB.
Where state lives¶
| Data | Memory mode | PostgreSQL + Valkey mode |
|---|---|---|
| scenario states | process memory | Valkey key <FASTMOCK_VALKEY_PREFIX>scenario:<name> |
| key-value entries | process memory | Valkey key <FASTMOCK_VALKEY_PREFIX>kv:<key> |
Valkey should therefore keep its data across restarts (the chart's bundled Valkey uses append-only persistence)
and must not evict keys without a TTL: the bundled Valkey uses maxmemory-policy volatile-lru. Scenario and
key-value changes are recorded in the audit log.
Limits¶
| Limit | Value |
|---|---|
| rendered scenario name | 512 bytes |
| state set through the admin API | 512 bytes |
ttlSeconds |
1 to 31536000 |
| concurrent transition retries | 8 |
| key-value key / value | 512 bytes / 1 MiB |
| scenarios listed | 10,000 |