Smart actions
A smart action is a list of conditions and a list of steps. On each exchange that meets its conditions, it takes its steps in order: set a header, block the request, hold the response, highlight the exchange, save a value, send a request.
The Smart actions window
Section titled “The Smart actions window”Open it with the lightning-bolt button beside the Scripts button in the top bar, or Open smart actions in the command palette.
The window shows the actions of the session chosen in the main window, and follows it when you switch tabs. Actions are saved with the session and come back when zhttp restarts.
On the left is the list of actions. Each row shows:
- a switch to turn it on or off;
- its name;
- how many exchanges it has matched since zhttp started. Point at the count to see when it last did;
- ! when it can’t run;
- REQ or RES for the message it runs on, and its conditions in a line.
+ adds an action. A new one is named New action, runs on the response, matches every URL and is switched off. Right-click an action to Export… or Remove it; the × on the row pointed at, and Delete, remove it too.
On the right are the action’s name, its switch, When and Then. A change applies as you make it, to traffic from then on. A field applies when you leave it or press Enter.
Request or Response picks the message the action runs on. An action on the request runs before there is a response: it isn’t offered the conditions and steps that need one.
Match All needs every condition met, Any one of them. + Condition adds one.
| Condition | Tests | By |
|---|---|---|
| URL | The whole URL, ignoring case. * stands for any run of characters: https://api.example.com/v2/*. |
matches, does not match |
| Method | The method, picked from a list | is, is not |
| Status | The response’s status | is, is not, at least, below |
| Duration | Milliseconds from the start of the request to the response’s last byte | at least, below |
| Size | The response’s body in bytes, as it travelled | at least, below |
| Request header, Response header | The values of the header you name | contains, is, is there, is missing |
| Request body, Response body | The body as text, its Content-Encoding removed |
contains, does not contain |
| Request JSON, Response JSON | The values a path reaches in a JSON body | is, is not, contains, is there, is missing, at least, below |
| GraphQL operation | The names of the GraphQL operations the request carries | is, is not |
| Variable | The value of the variable you name | is, is not, contains, is there, is missing, at least, below |
| Count | How many exchanges have met the other conditions, this one too | is, at least, below, every |
- Text is compared ignoring case. A JSON value compares as text: a string as itself, any other value as its JSON, such as
true,42or{"plan":"pro"}. - is not is met when none of the values is.
- A path reads like
data.items[0].id.[*]takes every element, and..ideveryidat any depth. - A body that isn’t JSON has nothing at any path.
Count every 3 is met by the 3rd, 6th, 9th exchange and so on. An action has one count at most, and only with All. The count starts again when you change the action, and when zhttp restarts.
+ Step lists the steps in five groups. Drag a step by its grip to move it. Steps run top to bottom.
In the steps below, the message is the one the action runs on: the request or the response.
Change
Section titled “Change”| Step | Does |
|---|---|
| Set header | Gives the message one header of that name, of that value. The first of that name keeps its place; the others go. |
| Remove header | Removes every header of that name |
| Set query | Gives the request’s URL one query parameter of that name, of that value. On the request only. |
| Replace in body | Puts the replacement in place of each match. Aa matches case. .* makes what is found a regular expression, whose groups the replacement names as $1, $2. |
| Set JSON value | Sets what the path reaches in a JSON body. The value is JSON: "pro", true, {"id":1}. The body must have something at the path. |
| Set status | Makes the response’s status the one you give, 200 to 599. On the response only. |
| Block | Answers the app with the status and body you give, in place of sending the request. Without a body, the answer names the action. On the request only. |
| Delay | Waits that many milliseconds, up to 600000, before the message goes on |
| Step | Does |
|---|---|
| Hold request | Holds the request in the Breakpoints panel, as a breakpoint does. On the request only. |
| Hold response | Holds the response. On an action on the request, it holds that request’s response when it arrives. |
| Hold next request | Holds the next request to a URL, once. * works as it does in a URL condition. Each match sets it again. |
The panel says Held by and the action’s name. Resume, Respond… and Drop work as they do for a breakpoint.
| Step | Does |
|---|---|
| Highlight | Highlights the exchange in red, orange, yellow, green, blue or purple |
| Comment | Sets the exchange’s comment |
| Favourite | Makes the exchange a favourite |
| Notify | Shows a message at the bottom right of the main window: the action’s name and the message, or the exchange when there is none. Show shows the exchange. Pick Every time, At most once a minute or At most once in 10 minutes. |
Variables
Section titled “Variables”| Step | Does |
|---|---|
| Save value | Sets a variable from Response body, Response header, Request body or Request header: the first value a path reaches in a JSON body, or the value of the header you name. Response body and Response header are offered on an action on the response only. |
| Increment | Adds the amount to a variable, 1 when you leave it empty. A variable that isn’t set counts from 0. |
| Step | Does |
|---|---|
| Replay | Sends the request again, as it was captured. Its body must have been captured in full. |
| Send request | Sends the method and URL you give, with headers, one Name: value a line, and a body |
| Run script | Runs a script on the message, written as in the Scripts window: onRequest on an action on the request, onResponse on the response. What it logs goes to Activity. |
| Run action | Takes the steps of another action of the session in its place. See Run action. |
Replay and Send request go on a connection made like the exchange’s own, so the server sees the app’s fingerprint. What they send is captured in the session. It goes through the session’s rules, but no smart action runs on it.
Templates
Section titled “Templates”The value of Set header, Set query and Set JSON value, the replacement of Replace in body, the text of Comment and Notify, the body of Block, and the URL, headers and body of Send request can hold:
| Write | For |
|---|---|
{{name}} |
The variable name. A string as itself, any other value as its JSON. |
{{$method}} |
GET, POST and so on |
{{$url}} |
The whole URL |
{{$host}} |
api.example.com |
{{$path}} |
/v2/items, without the query |
{{$status}} |
The response’s status |
{{$duration}} |
Milliseconds from the start of the request to the response’s last byte |
{{$count}} |
How many exchanges have met the conditions, this one too |
A step fails on a variable that isn’t set, on {{$status}} before there is a response, and on {{$duration}} before the response has ended.
When steps run
Section titled “When steps run”The steps that change, hold or answer the message are those under Change and Hold but Hold next request, and Run script. An action with one of them runs on the message as it arrives, before it goes on. Its Save value, Increment and Hold next request steps run then too. Its Highlight, Comment, Favourite, Notify, Replay and Send request steps run once the message has been captured.
An action with none of them runs once its message has been captured.
An action that changes, holds or answers the message can’t test Duration.
When a step fails
Section titled “When a step fails”A step that fails stops the steps after it, and the error shows in Activity in red.
On a message that hasn’t gone on yet:
- a request is not sent. The app gets a
502whose body startszhttp's smart action "Name" failed on this request:, followed by the error; - a response is replaced with that
502, sayingon this response.
When an action can’t run
Section titled “When an action can’t run”Why shows in red under the condition or step at fault, or under the action’s name. The row in the list shows !. The session’s other actions still run. An action can’t run when:
- it has no condition;
- it runs on the request and has a condition or step that needs the response, or it runs on the response and has a step for the request only;
- it changes, holds or answers the message and tests Duration;
- it has two counts, or a count with Any;
- a name, a URL or a variable a part needs is empty, or a number isn’t one;
- a status isn’t from
200to599, or a delay from1to600000; - a path, a regular expression, a template or a script doesn’t read;
- a step after Block changes or holds the request, or the action both blocks and holds it;
- a Run action step has no action chosen, or runs one that runs it back.
Run action
Section titled “Run action”Run action picks one of the session’s other actions. Its steps run in the place of the step, whatever its conditions and whether it is switched on. Changing that action changes every action that runs it.
An action can’t run one that runs it back. The step says so: it loops: Sign in → Refresh → Sign in.
Activity, Test and Variables
Section titled “Activity, Test and Variables”The tabs under the builder show the action chosen. Drag the line above them to make them taller.
Activity lists the latest 200 exchanges the action matched or failed on, newest first:
- when it ran;
- the entry ID: click it to show that request in the main window;
- the method, status and URL;
- the steps it took, or why it failed.
What its scripts log is listed there too. Clear empties the list.
Test tries the action on the request selected in the main window. Click Run. Nothing is sent or held, and no variable changes. It shows Matched or Not matched, each condition met or not and what it read, then each step and what it did, up to one that failed. For an action that changes the message, the message as its steps made it follows. The count goes on from the action’s own.
Variables lists the session’s variables. They are the variables its scripts share, and they work as they do there: edit them, Add one, or delete one with ×.
Export and import
Section titled “Export and import”- ⋯ › Export all… writes every action to one
.jsonfile. - Right-click an action › Export… writes that action, and the actions its Run action steps run.
- ⋯ › Import…, or Import… while there are no actions, takes one or more exported files. Imported actions go after the ones there are, switched on or off as they were saved, and their Run action steps run the actions imported with them.
Variables are not exported. A file with a condition or a step this zhttp doesn’t have is not imported.
With rules and scripts
Section titled “With rules and scripts”Smart actions run after the session’s rules. On a message that hasn’t gone on, its scripts run first, then each smart action in the list’s order, each given what the one before made. A breakpoint or a hold step then holds what they made. A request Block answers goes no further.
A request you replay from the list or send from the composer runs smart actions as any other does.
| Keys | In the Smart actions window |
|---|---|
| Enter | Apply the field |
| Delete | Remove the action, in the list |
| Esc | Close the window |
Recipes
Section titled “Recipes”Change api.example.com to the app’s own host. Switch the action on once it is built.
Flag slow responses
Section titled “Flag slow responses”When Response:
- Duration at least
2000ms
Then:
- Highlight orange
- Comment
Slow: {{$duration}} ms
Notify after five 401s
Section titled “Notify after five 401s”When Response, Match All:
- URL matches
https://api.example.com/* - Status is
401 - Count every
5
Then:
- Notify
{{$count}} requests to {{$host}} got a 401, At most once a minute
Add a header to every API request
Section titled “Add a header to every API request”When Request:
- URL matches
https://api.example.com/*
Then:
- Set header
X-Debugto1
Fail every third checkout with a 503
Section titled “Fail every third checkout with a 503”When Request, Match All:
- URL matches
https://api.example.com/v1/checkout* - Method is
POST - Count every
3
Then:
- Block
503, bodyService unavailable
The server never gets the requests that are blocked.
Keep a login token and send it
Section titled “Keep a login token and send it”Two actions. The first keeps the token a login returns. When Response:
- URL matches
https://api.example.com/v1/auth/login* - Status is
200
Then:
- Save value
tokenfrom Response bodydata.accessToken
The second sends it on every request once there is one. When Request:
- URL matches
https://api.example.com/* - Variable
tokenis there
Then:
- Set header
AuthorizationtoBearer {{token}}
Hold checkout once the cart changes
Section titled “Hold checkout once the cart changes”When Response:
- URL matches
https://api.example.com/v1/cart/items* - Method is
POST
Then:
- Hold next request
https://api.example.com/v1/checkout*
The next checkout waits in the Breakpoints panel. Each item added sets the hold again.