Request files
The request files apigenie test runs are written in the httpYac 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) |
# @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.