Scripts, tests and the runner

Scripts are small pieces of JavaScript that run around a request. A pre-request script runs before the request is built — to set a timestamp, sign something, or pick a value. A test script runs after the response — to check it and to save values for the next request. The runner sends a whole collection or folder, with its scripts and tests, as many times as you like.

Where scripts go

• A request: its Scripts pane, with a Pre-request and a Tests editor. (WebSocket tabs have no scripts.)
• A folder or a collection: Settings… → Scripts. These run for every request inside.

In the editors, Tab inserts two spaces and mod+enter sends the request.

Snippets

Buttons above the editors drop in a ready-made line:

With AI turned on, ✦ Write tests writes tests from the request and its last response — see Write tests.

How scripts run

A safe sandbox

Scripts run in a sandboxed frame plus a Worker. They have no network access and no access to DialCatz itself, its storage or the rest of the app — a script can read the request and response and set variables, nothing more.

• Each script is stopped after 10 seconds.
• Top-level await works, and async tests are awaited.

The order scripts run in

For each request:

1. The collection’s pre-request script, then each folder’s from the outside in, then the request’s own.
2. The request is built (with any variables those scripts set) and sent.
3. The collection’s tests, then each folder’s, then the request’s own.

Each script sees the variables the scripts before it set. Results from outer scripts are labelled Collection X · or Folder Y ·, so you can tell where a test came from.

Variables in scripts

dc.env.set() (and Postman’s pm.environment.set() and friends) change the variables the next steps see. When the request finishes, the changes are saved into the request’s environment — the collection’s environment or the active one. With no environment, they go into the globals.

Values are stored as strings: dc.env.set('count', 3) stores "3".

Results

Results show in the response’s Tests tab: PASS or FAIL per test, script errors, Variables set: … and every log line. A failing test or a script error opens that tab on its own.

The dc API

Everything a script needs is on the dc object.

dc.request

Available in both pre-request and test scripts.

dc.response

Available in test scripts only.

dc.env

dc.test and dc.expect

dc.test(name, fn) records a test called name. It passes when fn runs without throwing; fn may be async.

dc.expect(value) checks a value. Its matchers:

Put .not in front of any matcher to turn it around: dc.expect(body.error).not.toBeDefined().

dc.data and logging

An example

// Tests on a login request: check it, then keep the token for the next requests
dc.test('logged in', () => {
  dc.expect(dc.response.status).toBe(200);
  dc.expect(dc.response.json()).toHaveProperty('data.token');
});

dc.test('fast enough', () => {
  dc.expect(dc.response.time).toBeLessThan(500);
});

dc.env.set('token', dc.response.json().data.token);

With a secret token variable and Auth set to Bearer token {{token}} on the collection, every other request in it is now signed in.

Postman scripts (pm)

Scripts imported from Postman keep working: DialCatz understands the common part of Postman’s pm API.

Because pm.environment, pm.globals and pm.variables share one store, a value set through any of them is saved the same way as with dc.env.set — into the request’s environment, else the globals.

The collection runner

The runner sends a collection or folder from top to bottom — in tree order — with all its scripts and tests. Variables a script sets are there for the next request, so a login at the top can feed everything after it.

Open it with Run… in the right-click menu of a collection or folder. The dialog, Run “<name>”, says how many requests it holds and which environment it will use.

Set up a run

• Tick the requests to run. A tests badge marks the ones that have tests.
• Data file — Choose CSV or JSON… (.csv, .tsv, .txt or .json). One iteration per row; its columns become {{variables}} and pm.iterationData (and dc.data). A CSV needs a header row; a JSON file must be an array of objects.
• Iterations — 1 to 100, or up to 10,000 with a data file.
• Delay (ms) — a pause between requests, 0 to 60,000.
• Stop on failure — stop at the first failed test or failed call.

A data row’s values win over the environment and the globals for that iteration.

Results

While it runs: Running… N done, with Stop. When it finishes, the cat says All good or Finished with problems, with totals — sent, passed, failed and the total time in ms — and a table:

Then:

• Export results — JSON (everything) or JUnit XML (for CI tools).
• Change selection — back to the request list.
• Run again — the same run once more.

Limits

• Scripts have no network access and stop after 10 seconds.
• The runner does at most 100 iterations, or 10,000 with a data file.
• The pm API covers the parts listed above, not all of Postman’s.

Last updated 2026-11-03