# Request files

Source: https://apigenie.pl/docs/reference/cli/test/requests
Part of the reference of [test](https://apigenie.pl/docs/reference/cli/test.md).
Its other pages: [Variables and OAuth 2](https://apigenie.pl/docs/reference/cli/test/variables.md), [Assertions and scripts](https://apigenie.pl/docs/reference/cli/test/assertions.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).

The request files `apigenie test` runs are written in the [httpYac](https://httpyac.github.io/) flavour of the `.http`
format, which the JetBrains HTTP client and VS Code's REST Client read too. Directories are searched
for `.http` and `.rest` files.

A file is split into regions by lines starting with `###` (the rest of the line is the region's
title). A region has comments and directives (`#` or `//`), variable definitions, the request line
(`METHOD URL [HTTP/1.1]`; a URL alone is a `GET`), headers up to the first blank line, and a body up
to the next region, script or assertion. Lines starting with `?` or `&` right after the request line
continue the URL. A body of `< ./file.json` is read from that file, `<@ ./file.json` with its
variables substituted. Requests run in the order of the file, files in the order given.

`http://` and `https://` URLs both work. For `https://` (and `grpcs://`, `wss://` and `mqtts://`
alike), the server's certificate is checked against the system's root certificates and the URL's
host name. `--ca-cert FILE` adds authorities,
such as a test CA or a company's root, and `--insecure` skips the check. `SSL_CERT_FILE` replaces
the system's roots. A certificate that is rejected fails the request with the reason, for example
`no response: TLS with 10.0.0.5:443: certificate verification failed: The certificate is not
correctly signed by the trusted CA`.

A server behind mutual TLS asks for a client certificate: `--client-cert client.pem --client-key
client.key` presents one to every `https://`, `grpcs://`, `wss://` and `mqtts://` server that asks
(with `--insecure` too). The key must be PEM and not encrypted; a file that can't be read, or a key
of another certificate, stops the run with exit status 2. Without one, such a server fails the
request, for example `no response: TLS with api.example.com:443: the peer refused the connection:
the server requires a client certificate`. TLS sessions aren't resumed (every connection does a
full handshake), and certificates aren't checked for revocation (no CRL or OCSP).

| Directive | Meaning |
| --- | --- |
| `# @name list` | Names the request, so that others can refer to its response |
| `# @ref list` | Runs `list` first, unless it already ran |
| `# @forceRef list` | Runs `list` first, every time |
| `# @operation getPet` | Checks the request as the operation `getPet` of `--spec` (an AsyncAPI document's operation of an HTTP, WS or MQTT channel); for a GraphQL request, the operation to run (`operationName`) |
| `# @operation off` | Doesn't check the request against `--spec`, nor count it in the coverage |
| `# @channel pickupDesk` | WS and MQTT: checks the messages against that channel of the AsyncAPI document |
| `# @timeout 8000` | WS and MQTT, GraphQL subscriptions, gRPC client and bidi streams: waits up to 8000 ms for messages (`--message-timeout`, 5000 by default) |
| `# @expect 2` | WS and MQTT, GraphQL subscriptions: stops waiting after 2 messages; `0` doesn't wait |
| `# @property content-type application/json` | MQTT 5: a property of the messages the region publishes (see [MQTT 5 properties](/docs/reference/cli/test/websocket-mqtt#mqtt-5-properties)) |
| `# @disabled` | Skips the request |
| `# @postman` | Enables the collection-import compatibility API for this file |
| `# @title`, `# @description`, `# @tag`, `# @no-log`, `# @no-redirect`, `# @verbose`, ... | Accepted and ignored |

Any other directive is a warning: the request still runs.