Script API reference

Most checks need no code — see assertions and extractor rules below for the no-code equivalents of the two most common jobs. This page is for the cases where logic is genuinely required.

Where scripts run

A request can carry two scripts. Each is written in JavaScript or Python, chosen per script — a pre-script in Python and a post-script in JavaScript on the same request is fine. JavaScript is the default.

The order of a request

1. {{variables}} are resolved from the environment and collection.
2. Pre-request extractor rules run.
3. The pre-request script runs. Its header and parameter changes are merged in.
4. The body is built and the request is sent.
5. Post-response extractor rules run.
6. The post-request script runs, so it can override anything an extractor rule just set.
7. Assertions are evaluated, with any script assertions appended to them.

A request passes when every assertion passes. When it has no assertions at all, it passes on a status below 400.

The qc bindings

qc is how you change the request and record results. Python uses snake_case, JavaScript uses camelCase. Only set, expect and test are spelled the same in both.

qc.get_header and qc.get_param read what is currently staged on the outgoing request, not what came back. Response headers are on response.headers.

What is handed to your script

Alongside qc, these are available without importing anything.

qc.expect(status_code == 200, "expected 200")     # correct
# qc.expect(response.status == 200, ...)            # AttributeError

qc.expect(response.status === 200, "expected 200"); // correct
// qc.expect(status_code === 200, ...);              // ReferenceError

Execution limits

Each script runs in a separate process, so it cannot interfere with the run around it. Three consequences worth knowing:

• 30 seconds. A script running longer is stopped.
• Failure is silent and total. If the script errors, exceeds the timeout, or exits non-zero, every effect it had is discarded — headers, parameters, stored values and assertions alike. The request then carries on as though the script were not there.
• The runtime is the bundled one.Python runs under the agent's own interpreter and JavaScript under its bundled Node, so your system versions are irrelevant.

Worked examples

Chaining a value into the next request

The most common reason to write a post-script. Sign in, keep the token, and let every later request use it as {{auth_token}}.

const body = response.json();
qc.set("auth_token", body.access_token);
qc.set("user_id", body.user.id);

body = response.json()
qc.set("auth_token", body["access_token"])
qc.set("user_id", body["user"]["id"])

A later request now uses {{auth_token}} in a header or {{user_id}} in its path, exactly like an environment variable. Values set this way persist for the rest of the run.

Asserting something an operator cannot express

Use qc.expect for a condition you can state in one line, and qc.test when the check might throw.

const orders = response.json().orders;

qc.expect(orders.length > 0, "expected at least one order");

qc.test("orders are newest first", () => {
  const dates = orders.map(o => new Date(o.created_at).getTime());
  const sorted = [...dates].sort((a, b) => b - a);
  if (JSON.stringify(dates) !== JSON.stringify(sorted)) {
    throw new Error("orders are not sorted by created_at descending");
  }
});

qc.test("every order totals correctly", () => {
  for (const o of orders) {
    const sum = o.items.reduce((t, i) => t + i.price * i.qty, 0);
    if (Math.abs(sum - o.total) > 0.01) {
      throw new Error(`order ${o.id}: items sum to ${sum}, total says ${o.total}`);
    }
  }
});

orders = response.json()["orders"]

qc.expect(len(orders) > 0, "expected at least one order")
qc.expect(status_code == 200, "expected 200")

def totals_match():
    for o in orders:
        total = sum(i["price"] * i["qty"] for i in o["items"])
        assert abs(total - o["total"]) < 0.01, \
            f"order {o['id']}: items sum to {total}, total says {o['total']}"

qc.test("every order totals correctly", totals_match)

Each qc.expect and qc.test appears as its own line in the results, beside the no-code assertions, using the message or name you gave it. Write those as statements of what should be true — they are what somebody reads when the run goes red.

Setting a header and a parameter before sending

A pre-request script is for anything the request cannot express as a static value — a timestamp, a nonce, a computed signature.

const ts = String(Math.floor(Date.now() / 1000));

qc.setHeader("X-Request-Time", ts);
qc.setHeader("X-Idempotency-Key", `order-${ts}`);
qc.setParam("trace", "qaclan");

// Only add the debug header when the environment asks for it.
if (env.DEBUG_MODE === "true") {
  qc.setHeader("X-Debug", "1");
}

import time

ts = str(int(time.time()))

qc.set_header("X-Request-Time", ts)
qc.set_header("X-Idempotency-Key", f"order-{ts}")
qc.set_param("trace", "qaclan")

if env.get("DEBUG_MODE") == "true":
    qc.set_header("X-Debug", "1")

env holds the variables of whichever environment the run selected, so one script behaves differently against staging and production without being edited.

Reading what is already staged

qc.get_header is case-insensitive, so you do not have to match how the header was originally spelled.

// Matches Authorization, authorization or AUTHORIZATION.
const auth = qc.getHeader("authorization", "");

if (!auth) {
  qc.setHeader("Authorization", `Bearer ${env.FALLBACK_TOKEN}`);
}

const page = qc.getParam("page", "1");   // case-sensitive
qc.setParam("offset", String((Number(page) - 1) * 50));

Extractor rules — pulling a value out without code

If all you want is one value from the response, you do not need a script. A request can carry extractor rules, each with three fields.

Integers index into arrays, so items.0.id takes the first item's id.

Two things fail quietly rather than failing the request:

• If the response is not JSON, every rule is skipped.
• If a path does not resolve, that rule is skipped and the variable is not set.

So a later request finding {{token}} unresolved usually means the extractor path was wrong, not that the request failed. The stored value is always text, with the prefix applied.

Assertions — checking a response without code

The other common job with a no-code equivalent. An assertion is a type, an operator and an expected value; full detail is on API testing.

Eight operators are available:

Reach for a script when a check needs more than one operator can say — comparing two fields to each other, verifying an order, or checking a computed total.

Browser scripts

A recorded browser journey is a real Playwright file you can open and edit. The language is chosen when the script is created and cannot be changed afterwards.

The two _test values use an underscore. A hyphen is rejected.

qaclan web record --feature <feature_id> --name login --language typescript_test

What a browser script is given at run time

Whatever the language, the generated file reads its configuration from environment variables set by the runner. If you hand-edit a script or import one of your own, honouring these keeps it working with the run dialog.

Where to go next

• API testing — collections, requests, auth and the assertion builder
• Negative testing and schema drift — checks that generate their own cases
• Environments and secrets — where env comes from
• Web testing — recording, editing and hardening browser scripts