Stubs on spectralab

YAML Reference

Mon, 01 Jan 0001 00:00:00 +0000

YAML Reference#

Each .yaml / .yml file in the stubs directory defines one endpoint. Every field is optional unless marked required.

Minimal Stub#

id: my-endpoint
path: /some/path
response:
 status_code: 200

Full Stub — Every Option#

id: my-endpoint
method: POST  # HTTP method (empty = match any)
path: /webhooks/event  # URL path (exact match)
path_glob: /users/**  # URL path glob (see Path Patterns)
path_regex: '^/orders/[0-9]{5}$' # URL path regex (RE2 — anchor with ^…$ yourself)
headers: # Request headers to match (optional)
 X-Event: event.created
query: # Query params to match (optional)
 token: abc123
payload: '{"type":"test"}' # Exact request body to match (optional)
payload_contains: '{"event":"user.created"}' # Partial JSON request-body match (optional)
response:
 status_code: 201 # HTTP status (default: 200)
 body: '{"ok":true}' # Response body (optional)
 headers: # Response headers (optional)
 Content-Type: application/json
 X-Custom: myvalue
 delay: 300ms  # Simulated latency (optional)
 echo: true # Return request body verbatim (optional)
 template: true # Enable Go template in body/headers (optional)

Field Reference#

Field	Required	Type	Description
`id`	yes	string	Unique endpoint identifier. Used as the stub name in logs and the dashboard.
`method`	no	string	HTTP method the request must use (`GET`, `POST`, …). Empty matches any method.
`path`	no*	string	Exact request path to match.
`path_glob`	no*	string	Segment-wise glob path match (`*`, ``, `?`).
`path_regex`	no*	string	Go RE2 regex path match (not implicitly anchored).
`headers`	no	map	Request headers that must be present with exact values.
`query`	no	map	Query params that must be present with exact values.
`payload`	no	string	Exact request body the request must match (byte-level).
`payload_contains`	no	string	Partial JSON spec the request body must contain.
`response.status_code`	no	int	HTTP status code to return (default: `200`).
`response.body`	no	string	Response body. Ignored when `echo: true`.
`response.headers`	no	map	Response headers to send.
`response.delay`	no	duration	Simulated latency before responding (e.g. `200ms`, `1s`).
`response.echo`	no	bool	Return the request body verbatim.
`response.template`	no	bool	Process `body`/headers as a Go template.
`responses[]`	no	list	Multiple response variants with weights (see below).

* Exactly one of path / path_glob / path_regex per stub. Setting more than one fails to load with a parse error naming the stub ID and the conflicting fields. A stub with none of them is also invalid — you must match on something.

Matching

Mon, 01 Jan 0001 00:00:00 +0000

Request Matching#

An endpoint matches a request when all specified conditions are met:

Field	Behavior
`method`	Must equal the request method. Empty matches any method.
`path` / `path_glob` / `path_regex`	Exactly one path matcher — exact, glob, or regex.
`headers`	All listed headers must be present with the exact values.
`query`	All listed query params must be present with the exact values.
`payload` / `payload_contains`	The request body must match exactly, or contain the JSON subset.

Request matching is AND logic: every condition you specify must hold. Conditions you don’t specify are ignored.

Path Patterns

Mon, 01 Jan 0001 00:00:00 +0000

Path Patterns#

Simuhook supports three ways to match the request path. A stub may set exactly one of them.

Field	Semantics
`path`	Exact match on the raw URL path: `/api/users` matches `/api/users` only — never `/api/users/1` or `/api/users/1/orders`.
`path_glob`	Segment-wise glob with `*`, ``, and `?` wildcards.
`path_regex`	Go stdlib `regexp` (RE2). Not implicitly anchored — write `^…$` yourself for a full-path match.

Setting more than one is a load-time parse error naming the stub ID and the conflicting fields.

Payload Matching

Mon, 01 Jan 0001 00:00:00 +0000

Payload Matching#

Simuhook can constrain a stub to specific request bodies — two ways, depending on whether you need an exact byte match or a partial JSON match.

Field	Meaning	Use when
`payload`	The request body must match exactly (byte-level).	You want to enforce that your client sends precisely the body you expect.
`payload_contains`	The request body must be valid JSON that contains the given spec.	You want to match on a few fields and ignore everything else.

A stub may set at most one of the two — setting both is a load-time parse error. Specs must be quoted in YAML; invalid spec JSON is a load-time parse error.