# Assertions and scripts

Source: https://apigenie.pl/docs/reference/cli/test/assertions
Part of the reference of [test](https://apigenie.pl/docs/reference/cli/test.md).
Its other pages: [Request files](https://apigenie.pl/docs/reference/cli/test/requests.md), [Variables and OAuth 2](https://apigenie.pl/docs/reference/cli/test/variables.md), [Validation](https://apigenie.pl/docs/reference/cli/test/validation.md), [Generated requests](https://apigenie.pl/docs/reference/cli/test/generate.md), [GraphQL requests](https://apigenie.pl/docs/reference/cli/test/graphql.md), [WebSocket and MQTT requests](https://apigenie.pl/docs/reference/cli/test/websocket-mqtt.md), [Kafka requests](https://apigenie.pl/docs/reference/cli/test/kafka.md), [AMQP requests](https://apigenie.pl/docs/reference/cli/test/amqp.md), [gRPC requests](https://apigenie.pl/docs/reference/cli/test/grpc.md), [Importing collections](https://apigenie.pl/docs/reference/cli/test/import.md), [httpYac compatibility](https://apigenie.pl/docs/reference/cli/test/httpyac.md).

What a request checks about its response, and the JavaScript that runs before a request is sent
and after its response came.

## Assertions

A line `?? SUBJECT [ARGUMENT] PREDICATE [VALUE]` checks the response:

| Subject | Value |
| --- | --- |
| `status` | The status |
| `header NAME` | The header's value |
| `body` | The body; `body PATH` a value of the JSON body (`$.items[0].id`, `items[0].id` or `/items/0/id`) |
| `duration` | The time to the response, in milliseconds |
| `js EXPRESSION` | The value of a JavaScript expression with the scripts' API |

Predicates: `==`, `!=`, `>`, `>=`, `<`, `<=` (numbers when both sides are numbers), `startsWith`,
`endsWith`, `includes` (or `contains`), `matches` (a regular expression, `/.../flags` too),
`exists`, `isArray`, `isBoolean`, `isNumber`, `isString`, `isTrue` and `isFalse`. A `js` subject
without a predicate must be true. Variables are substituted in the argument and the value.

## Scripts

`{{` and `}}` on lines of their own enclose an httpYac script: before the request line it runs
before the request is sent, after it once the response came. JetBrains handlers work too:
`< {% ... %}` before the request line, `> {% ... %}` after it. Scripts run in a sandboxed
JavaScript engine (QuickJS) with no file system or network access, five seconds each. Both
flavours get the same API:

| Name | What it is |
| --- | --- |
| `response.status`, `response.statusCode` | The status |
| `response.headers` | Headers by lower-case name; `headers.valueOf(name)`, `headers.valuesOf(name)` |
| `response.body` | The body, parsed when it is JSON; `response.parsedBody`, `response.rawBody` |
| `response.contentType.mimeType`, `.charset` | The media type |
| `response.duration` | Milliseconds |
| `request.method`, `request.url`, `request.headers`, `request.body` | The request as written |
| `request.variables.set(name, value)`, `.get(name)` | Variables of this request (pre-request scripts) |
| `exports.name = value`, `client.global.set(name, value)` | Variables of the following requests |
| `client.global.get(name)`, `request.environment.get(name)` | A variable |
| `test(name, fn)`, `client.test(name, fn)` | A named check: it fails when `fn` throws (or its promise rejects) |
| `test.status(code)`, `test.header(name, value)`, `test.headerContains(name, text)`, `test.hasResponseBody()`, `test.totalTime(ms)` | httpYac's shortcuts |
| `assert(value, message)`, `client.assert(...)`, `assert.equal`, `assert.strictEqual`, `assert.deepStrictEqual`, `assert.notEqual`, `assert.fail` | Throws when the check fails |
| `console.log`, `console.warn`, ..., `client.log` | Lines of the request's log (`--verbose`, the reports) |

Variables are also local names of scripts when they are identifiers. A script that throws fails its
request. Changes an ordinary pre-request script makes to `request` are not sent: set variables
instead. Imported files opt into the header-addition API described below.