Scripting

Run JavaScript on matching requests and responses. Edit headers, query and JSON bodies, mock responses, keep state and call other services.

Mac iPhone and iPad

When a fixed rule is not enough, write a script. A script belongs to a host pattern and defines onRequest, onResponse or both. WireLens runs it inside the app for every matching exchange.

Add a script#

Open Tools ▸ Scripting and add a script with a host pattern and a name. A blank pattern is refused, so a script can never silently run on everything.

The snippet menu inserts working examples you can edit:

Add a request header
Rewrite a JSON field
Mock a 503 JSON body
Strip Cookie and Authorization
Drop a request with abort()

Scripting has a master switch. Turning it off stops every script without deleting any, and each script can also be switched off on its own.

The two hooks#

// Before the request leaves for the server.
function onRequest(req) {
  req.headers.upsert({ key: 'X-WireLens', value: 'scripted' });
}

// After the server answers, before the app sees it.
function onResponse(req, res) {
  var data = res.body.json();
  if (data && typeof data === 'object') {
    data.ok = true;
    res.body.text = data;
  }
}

Either hook can be async. WireLens waits for its promises, including $http calls, to settle before the exchange continues, up to the run's time limit.

Reading and changing an exchange#

In a script	What it does
`req.method`	The method. Assign to change it: `req.method = 'PATCH'`.
`req.url`	The full URL.
`req.originalUrl`	The URL before any rule changed it.
`req.headers.upsert({ key, value })`	Add a header, or replace it if it exists.
`req.headers.remove(name)`	Remove a header.
`req.query.set(name, value)`	Set a query parameter.
`req.query.remove(name)`	Remove a query parameter.
`req.body.text`	The body as text. Assign a string, or an object to write JSON.
`req.body.json()`	The body parsed as JSON.
`res.status`	The status. Assign to change it: `res.status = 201`.
`res.headers.get(name)`	Read a response header.
`res.body.text`, `res.body.json()`	The response body, the same way as the request's.

Built-in functions#

Function	What it does
`mock(status, headers, body)`	Answers locally. The server is never contacted.
`abort()`	Closes the client connection without contacting the server.
`comment(text)`	Adds a comment to the flow, which shows in the traffic list.
`console.log(...)`	Writes to the script's log.

function onRequest(req) {
  mock(503, { 'Content-Type': 'application/json' }, {
    error: 'service_unavailable',
    message: 'Mocked by WireLens'
  });
}

State, environment and HTTP#

$state is a small key-value store shared by every run in this app session: $state.get(key), $state.set(key, value), $state.remove(key) and $state.all(). Values are stored as strings. Use it to count requests, remember a token from one response and add it to the next request, or fail every third call.
$env holds values you do not want in the script itself, such as API keys, with the same get, set, remove and all. Every $env value is redacted from console output and error messages.
$http(options) calls another service and returns a promise. Pass url (absolute http or https), and optionally method, headers, body and timeout. The number of concurrent calls per run is capped.

async function onRequest(req) {
  var count = Number($state.get('checkout') || 0) + 1;
  $state.set('checkout', String(count));
  if (count % 3 === 0) {
    mock(502, { 'Content-Type': 'application/json' }, { error: 'flaky upstream' });
    return;
  }
  var token = await $http({ url: 'https://auth.example.com/token', method: 'POST' });
  req.headers.upsert({ key: 'Authorization', value: 'Bearer ' + token.body });
}

Where scripts run#

Scripts run in the WireLens app, never inside the capture engine itself, so a slow or broken script cannot take capture down with it. Each run has a time limit, and an error in a script is reported on the flow instead of failing silently.

For HTTPS, the host must be decrypted before a script can see it. See SSL Proxying.

Free and Pro#

The free plan runs one script. Pro removes the limit.

From MCP#

The MCP tool add_script_rule takes a host pattern plus on_request and/or on_response source. If a static stub or a header change is all you need, Map Local and Rewrite are easier to review.

Something here is unclear, or wrong for your setup? Contact support or write to support@wirelens.app.