Request Shape Reference

Every defineSample, beforeEach and authorize hook receives the request the sampler is about to send, and shapes it in place.

Note

This is a value in memory, not a file. The sampler generates it from your API description on every run — there is no request.json to edit. See Virtual Request Samples.

Fields

Field	Type	Meaning
method	string	The HTTP method, as the description spells it
origin	string	Scheme, host and port, from the description’s servers
path	string	The path template, with {param} placeholders still in it
pathParameters	Record<string, unknown>	Values substituted into the template
query	Record<string, unknown>	Query parameters, serialized per the description’s style
headers	Record<string, string | string[] | undefined>	Request headers
cookies	Record<string, unknown>	Cookies
body	unknown	The request body, if the Transaction has one
bodyEncoding	string | undefined	How to encode the body, for binary media types
authorize	boolean	Whether this request wants credentials — see authorization

Example

npx thymian sampler show 'POST /astronauts (application/json) -> 201 (application/json)'

{
  "authorize": false,
  "cookies": {},
  "headers": {
    "content-type": "application/json",
    "accept": "application/json"
  },
  "method": "post",
  "origin": "http://localhost:3000",
  "path": "/astronauts",
  "pathParameters": {},
  "query": {},
  "body": {
    "name": "string",
    "password": "string",
    "email": "string",
    "role": "Commander"
  }
}

Shaping it

Two equivalent ways, both writing into the same object:

// directly
request.headers['x-trace-id'] = 'abc';
request.pathParameters['id'] = 42;
request.body = { name: 'Sarah' };

// through the typed setters
utils.setHeader('x-trace-id', 'abc');
utils.setPathParam('id', 42);
utils.setBody({ name: 'Sarah' });

The setters exist so the compiler knows the name and the value type; there is no behavioural difference. Both mutate in place — a hook returns nothing.

path is a template

path stays /astronauts/{id}, and pathParameters carries the values. The substitution and the serialization of query parameters happen after your hooks have run, using the styles your description declares — so a hook sets a value and does not have to know how it is spelled on the wire.

utils.setPathParam('id', 42); // yes
request.pathParameters.id = 42; // the same thing
request.path.id = 42; // no — `path` is a string, and this is a compile error

Bodies from files

export const withFixture = defineSample(
  'POST /astronauts (application/json) -> 201 (application/json)',
  (draft, utils) => {
    draft.body = utils.readJson('./fixtures/astronaut.json');
  },
);

A relative path resolves against the hook file’s own directory. readFile returns the bytes, for a binary media type.

The response side

An afterEach hook receives the response instead:

Field	Type
statusCode	number
headers	Record<string, string | string[] | undefined>
body	string | undefined — the raw body
bodyEncoding	string | undefined
trailers	Record<string, string>
duration	number — milliseconds

A utils.request call is the exception: it returns { statusCode, headers, body } with a JSON body already parsed and typed by the Selector you asked for.