Comment on page
Scripting
Proxyman offers a scripting feature that the developer could write the JS code to manipulate the Request/Response in a flexible way.
- Implement Map Local / Map Remote / Breakpoint by JS Code. 100x Faster
- Change the Request Content, includes Domain, Host, Scheme, Port, Path, HTTP Method, HTTP Headers, Query, Body (Encoded-Form, JSON, plain-text)
- Change the Response Content, includes HTTP Status Code, HTTP Headers, Body (JSON, Encoded-Form, plain-text, binary...)
- Provide plenty of built-in addons and libraries for common tasks, such as Hashing, Encode/Decode, JSON-Text transformer, Beautify,...
- Able to write your own JS Addons or Libraries
- Designed to replace Rewrite GUI Tool from Charles Proxy
- Assign and receive shared States between each script or current session with ShareState or Environment Variables

You can access the Scripting Tool by:
- Script Menu -> Script List (⌥⌘I)
- Open Menu Context from Right Click on the Flow -> Tools -> Scripting
From Proxyman 2.27.0+, the Scripting Tool can work with GraphQL Request by a specific QueryName. Please check out the following GraphQL Document.
The following guide will show you how to write JS code to change the Request domain from Production to Localhost and change the Response Body
- 1.Make sure you enable SSL for this domain before creating the script)
- 2.Open Scripting Tool and create a new Script Entry (⌘N). You can right-click on the Request -> Tools -> Scripting => Proxyman will create a Script too
- 3.Give the name and define a Matching Rule.
- 4.Ex: Name=Test on Localhost endpoint, URL=https://proxyman.io
- 5.Enable Run Script on Request and Response checkbox
- 6.Start writing JS code for
onRequest
function
onRequest(context, url, request) {}
// Import UUID addons
const { uuidv4 } = require("@addons/UUID.js");
/// This func is called if the Request Checkbox is Enabled
/// You can manipulate the Request Data here before the request hits on the server
/// e.g. Add/Update/Remove: host, scheme, port, path, headers, queries, comment, color and body (json, form, plain-text, base64 encoded string)
///
/// Use console.log(request) to see all available fields
/// Action Menu -> Import File to import a JSON file and use in the script. Or Import directly with request.bodyFilePath = "~/Desktop/myfile.json" (Applied for Response too)
/// Use global object `sharedState` to share data between Requests/Response from different scripts (e.g. sharedState.data = "My-Data")
///
function onRequest(context, url, request) {
// print log
console.log(request);
// Change Production domain -> Localhost
request.method = "GET";
request.scheme = "http";
request.host = "localhost";
request.port = 8000;
// Add new header
request.headers["X-New-Header"] = "Hello From Scripting feature";
request.headers["UUID"] = uuidv4(); // generate random UUIDv4
delete request.headers["Key-Need-Delete"];
// Update or Add a new Query
request.queries["name"] = "Proxyman";
// Update Body
var body = request.body;
body["name"] = "Proxyman";
request.body = body;
// Or Map the body with a local file (Proxyman 2.25.0+)
// request.bodyFilePath = "~/Desktop/mockdata.json";
// Done
return request;
}
context
, url
and request
objects are defined by:// context (readonly)
{
"scriptName": "<String> Your Script Name",
"matchingRule": "<String> Your Matching Rule",
"matchingMethod": "<String> Method",
"isEnableOnRequest": "Bool",
"isEnableOnResponse": "Bool",
"filePath": "<String> Script path",
"flow": { // Availble from 2.16.0+
"serverPort": "443",
"serverIpAddress": "104.18.230.83",
"clientIpAddress": "192.168.0.102",
"remoteDeviceName": "iPhone XR",
"remoteDeviceIP": "192.168.0.102",
"id": "51",
"clientPath": null,
"clientPort": "51494",
"clientName": null
},
}
// url (readonly)
url: String // => Present the full URL
// request
{
"method": "<String> HTTP Method. Accept string method. Ex: GET, POST, ...",
"scheme": "<String> Accept http or https",
"host": "<String> Host of the request. Ex: api.proxyman.io, localhost, ...",
"path": "<String>: Path of the URL. Ex: /v1/data",
"port": "<Int> Accept int port number. Ex: 443, 8080, ..",
"queries": "<[String: Any]> A JS Object (Dictionary) contains key values of the query",
"headers": "<[String: Any]> A JS Object (Dictionary) contains key values of the header",
"body": "Depend on the Content-Type header. It might be a dictionary for JSON and form, Plain Text or Base64 Encoded String",
"bodyFilePath": "<String><Optional> Set a body with a local file. See example in Snippet Code Page"
"rawBody": "<Readonly>: A raw body String or Base64 encoded string if it's a binary",
"preserveHostHeader": "<Bool> Preserve the Host",
"isURLEncoding": "<Bool> Determine if Proxyman will perform URLEncoding when constructing the final URL. Default is True"
}
You can change any value of the request obj except
rawBody
If the body variable is invalid format due to incorrect Content-Type in the Header. Please consider using the rawBody and manually parse the string.
The type of
request.body
replies on the Content-Type Header.Content-Type Header | request.body |
application/json or JSON families | Javascript Object |
application/x-www-form-urlencoded | Javascript Object |
plain-text or text-based Content-Type, Ex: application/js, text/css, text/html, ... | String |
The rest (application/zip, application/octet-stream) | Base64 Encoded String |
Check out common JS code from Snipped Code Page
7. Start writing code on
onResponse
function/// This func is called if the Response Checkbox is Enabled
/// You can manipulate the Response Data here before it goes to the client
/// e.g. Add/Update/Remove: headers, statusCode, comment, color and body (json, plain-text, base64 encoded string)
///
/// Use console.log(response) to see all available fields
///
function onResponse(context, url, request, response) {
console.log(response);
// Update or Add a new header
response.headers["Content-Type"] = "application/json";
// Update status Code
response.statusCode = 500;
// Update Body
var body = response.body;
body["new-key"] = "Proxyman";
response.body = body;
// Or Map the body with a local file (Proxyman 2.25.0+)
// response.bodyFilePath = "~/Desktop/mockdata.json";
// Done
return response;
}
context
, url
, request
, and response
objects are defined by:// context (readonly): Same with onRequest
// url (readonly): Same with onRequest
// request (readonly): Same with onRequest
// response
{
"statusCode": "<Int> Status Code. Ex: 200, 400, 404,...",
"httpVersion": "<String><Readonly> The HTTP Version",
"statusPhrase": "<String><Readonly> HTTP Status Phrase. Ex Not Found, OK, ...",
"headers": "<[String: Any]> A JS Object (Dictionary) contains key values of the header",
"body": "Depend on the Content-Type header. It might be a dictionary for JSON and form, PlainText or Base64 Encoded String",
"rawBody": "<Readonly>: A raw body String or Base64 encoded string if it's a binary",
"bodyFilePath": "<String><Optional> Set a body with a local file. See example in Snippet Code Page"
}
You can change
statusCode
, headers
and body
from the response ObjIf the body variable is invalid format due to incorrect Content-Type in the Header. Please consider using rawBody and manually parse the string.
The type of
response.body
replies on the Content-Type HeaderContent-Type Header | request.body |
application/json or JSON families | Javascript Object |
application/x-www-form-urlencoded | Javascript Object |
plain-text or text-based Content-Type, Ex: application/js, text/css, text/html, ... | String |
The rest (application/zip, application/octet-stream) | Base64 Encoded String |
You must return
request
and response
object in onRequest
and onResponse
functionProxyman provides plenty of addons and libraries that help you achieve common tasks: Hashing, Encode/Decode, ...
On certain occasions, you might encounter Javascript errors due to syntax errors, invalid code, ... You can debug by looking at error messages on the console or using
console.log().
From Proxyman 2.32.0, we can use Scripting Tool as a Mock API. It means your request would never hit the server, and you have to define a Response Body. This behavior is the same with Map Local.
This feature is useful when the actual Restful API is not available yet. You can define and test it locally.
To enable the Mock API:
- 1.Open the Scripting Tool -> Select the Script
- 2.Enable Run as Mock API checkbox.

Enable Mock API
Then you can define a Response as usual:
function onResponse(context, url, request, response) {
// Init new body
var body = {};
body["new-key"] = "Proxyman";
response.body = body;
// Or map from a file
// response.bodyFilePath = "~/Desktop/myfile.json"
// Done
return response;
}
- You must return
request
andresponse
Object inonRequest
andonResponse
function. - Since Javascript doesn't have the Data object type, the Data Body will convert to Base64 Encoded String in Javascript.
- To pass Uint8Array, blob, or ArrayBuffer to the body, make sure you convert to Base64 Encoded String.
// Your binary, Uint8Array, blob data,...
var myData = fromFile();
// Import
const { btoa } = require('@addons/Base64.js');
// Convert to base64 encoded string
response.body = btoa(myData);
Last modified 2yr ago