HTTPS Format

The .https format

Pardon introduces a new format for describing the HTTP interaction: The HTTPS or “HTTP Schema” format.

An https file starts with a yaml block (which may be empty), followed by a sequence of request, response, and script blocks.

Each block starts with a specific sigil at the start of a line:

• >>> starts a request,
• <<< starts a response, and
• !!! starts a script.

Requests are parsed as KV data, then the method and URL, header lines. Any body content is separated from the headers by a blank line.

Lines following the URL starting with /, ? and & are appended to it, allowing long URLs to be broken up naturally.

Anatomy of an HTTPS request

sigil

>>> variant
x=y
POST https://service/path?query=value
header: value

content

kv data

>>> variant
x=y
POST https://service/path?query=value
header: value

content

HTTP-format request

>>> variant
x=y
POST https://service/path?query=value
header: value

content

Alternate request line

>>> variant
x=y
POST https://service/very/long/path
  /broken/up
  ?query=value
  &another=param
header: value

content

Responses start with a status code and optional status text, headers, and body content. x or * can be used in place of numbers in the status code, e.g., 2xx matches all 200 responses.

Semantics

The semantics of an https file is determined by their sub-extension.

• *.https is a collection https file, used as a template to match a single request and response.
• *.mix.https is a mixin template meant to extend a collection https file.
• *.flow.https is a program: executing a sequence of requests one-at-a-time.

Endpoints and Mixins

Standard *.https files represent an API endpoint: they are meant to match a single https request and its response.

Requests are matched against all endpoints: For each endpoint, the request is matched against each request block in turn, if any match, the endpoint is selected. Any mixins are then applied, with enabled and matching mixins applying their templates to the request, picking the first matching one (selected mixings can apply their own mixins as well).

Once the request is rendered, any script blocks immediately following the request are executed. The request could then be sent. The first matching response block in each selected layer is then applied to the response (only considering response blocks after the selected request). If any script blocks follow the response, they are executed too.

In https requests, the request sigil may have a variant

>>> {{?variant}}

And the response sigil may have an outcome

<<< {{?outcome}}

These variables would be available in the egress and ingress values, respectively.

Flows

Flows are usually executed by the test case-runner or scripts. These are structured in groupos of request and responses for that group.

In sequences, requests and responses are named and a response matching a request name works like a goto.

flow step	description
>>> label	a named request
<<< label	a named response - label = next request or outcome of flow
>>> label / 10	a named request that will run at most 10 times in this flow execution
<<< label +2s	a named response that will wait 2 seconds before executing the next request