Skip to content

Scripting

A script runs JavaScript on each exchange it matches. onRequest runs before the request goes to the server, and onResponse runs before the response goes to the app. Each can change the method, the path and query, the headers, the cookies, the status and the body.

For what a script is given and the helpers it can call, see the script reference. For scripts to copy, see the recipes.

Open it with any of:

  • the { } button in the top bar;
  • Ctrl Shift J, or Open scripts in the command palette;
  • right-click a request › Script…, which adds a script for that URL with any query string;
  • right-click a host or folder in Structure › Script…

The window shows the scripts of the session chosen in the main window, and follows it when you switch tabs. Scripts are saved with the session.

The Scripts window: three scripts listed in the order they run, the JavaScript of one that makes an account premium, and its console

On the left is the list, in the order the scripts run. Each row shows:

  • its number in the run order;
  • a switch to turn it on or off;
  • its name, and its URL under it;
  • REQ and RES for whether it runs on requests, responses or both;
  • a dot while it has changes not yet applied;
  • a red count of the errors it has hit since it was last applied.

+ adds a script from a template. Drag a script up or down to change when it runs. Right-click one to Duplicate it, Save as .js…, move it, or Remove it. Undo under the list puts back a script you just removed.

On the right, Name, URL and Method say which requests the script runs on. URL and method work as they do for breakpoints. Run on picks Request, Response or both.

Changes to a script don’t run until you Apply them (Ctrl S). Until then the last applied version keeps running on traffic, and Revert throws your changes away. Changes you haven’t applied stay in the editor when you switch scripts or close the window, but not when you quit zhttp.

While you type:

  • the script is checked as it would load. A syntax error, or a missing onRequest or onResponse, shows under the editor with its line underlined. Click it to go to that line.
  • the editor offers the names that match what you type: a script’s own, such as sha256(data, encoding = "hex"), the language’s keywords and the names already in the script. After a . it offers what is there, such as request. › headers, cookies… Enter or Tab puts one in, and Ctrl Space offers them at the caret.
  • Snippets inserts common code where the caret is. A snippet goes on the caret’s line when that line is blank, or else on a new line after it, indented to match.
  • Format (Shift Alt F) lays the script out as js-beautify does, two spaces an indent, keeping its comments. Ctrl Z takes it back.
  • Ctrl F finds text in the script.

Every script that matches a request runs, top to bottom. Each is given what the one before made of the request or the response. When a breakpoint matches too, the scripts run first and the breakpoint holds what they made.

Test (Ctrl Enter) runs the script as it is written, applied or not, on a captured request. Nothing is sent.

Test on picks the request. It lists the one selected in the main window first, then the latest requests the script’s URL and method match.

The Test tab shows the request, and the response when the script runs on responses. What was captured is on the left, what the script makes of it is on the right, and the changes are marked. A count beside Request and Response says how many lines changed.

The Test tab: the captured response says the plan is free, and the response the script makes says it is pro and premium

If the script fails, the error shows above, its line is underlined in the editor, and the right side says what zhttp would have done: Not sent for a request, Answered with a 502 for a response. What the script logs goes to the console, marked test.

A test uses a copy of the session’s variables: what it sets doesn’t reach them. It runs on the exchange as it was captured, so a request a script already changed gets changed again. The test needs the exchange’s bodies captured in full.

The Console tab shows what the script logs with console.log, console.warn and console.error, and why it failed, one line each:

  • when it ran;
  • the request’s entry ID: click it to show that request in the main window;
  • for an error, line N: click it to go to that line.

This script shows the selected script’s lines, All shows every script’s, with the script’s name. Filter keeps the lines that contain its text. Right-click › Copy all copies the lines shown.

The Variables tab lists the variables the session’s scripts share through shared. Smart actions read and set the same ones. They change as scripts set them. Edit a name or a value there, Add one, or delete one with ×. A string stays a string, so type it without quotes. Any other value must be JSON: a value that isn’t gets a red outline and isn’t applied.

Variables last when you edit a script, and are saved with the session.

Save as .js… writes one script to a file, with a header saying where it runs:

// ==zhttp==
// @name Premium account
// @url https://api.example.com/v2/me*
// @method GET
// @run response
// @enabled true
// ==/zhttp==
function onResponse(context, url, request, response) {
response.body.plan = "pro";
return response;
}

@method is left out for any method. @run is request, response or request, response.

⋯ › Export all… writes every script, in the order they run, and the session’s variables, to one .json file. ⋯ › Import… takes .js files and exported .json files, one or many. Imported scripts go after the ones there are, switched on or off as they were saved. Imported variables replace any of the same name. A .js file without a header is named after the file, gets no URL, and runs on whichever of onRequest and onResponse it defines.

What is saved, exported and duplicated is each script as it is written in the editor.

Blank Both functions, returning what they’re given
Add a request header Adds X-Debug: 1
Change a query parameter Sets page, removes cache
Edit a JSON response Adds debug: true to a JSON body
Replace the response Answers 200 with a JSON body of its own
Log each exchange Logs the method, URL, status and content type

A run is stopped after 1 second of running. Time spent in sleep doesn’t count. If a script throws, times out, returns nothing or has a syntax error:

  • the request is not sent, and its exchange ends;
  • the response is replaced with a 502 whose body starts zhttp's script failed on this response:, followed by the error.

The scripts after it don’t run. The error goes to the console in red, with its line, and the script’s row counts it.

Keys In the Scripts window
Ctrl S Apply the script
Ctrl Enter Test it
Ctrl N New script
Ctrl D Duplicate the script
Alt ↑ ↓ Move it up or down
Delete Remove it, in the list
Ctrl Space Offer what a script can use
Shift Alt F Format the script
Ctrl Shift Z, Ctrl Y Redo
Ctrl F Find in the script
Esc Close the window

On a Mac, Cmd works as well as Ctrl with S, Enter, N and D, and redo is Cmd Shift Z.

  • A script can’t send a request to another server. Changing scheme, host or port is an error.
  • Event streams and WebSockets go on as they came.
  • Scripts have no network or file access.
  • AI agents see scripts among the rules (zhttp_rules), and can add, change, test and reorder them. See AI agents.