Scripting
How to use the Scripting tool to modify the Request/Response by Javascript Code.
1. What's it?
Proxyman offers a scripting feature that the developer could write the JS code to manipulate the Request/Response in a flexible way.
2. Benefits
Implement Map Local / Map Remote / Breakpoint by JS Code. 100x Faster
Change the Request Content, including Domain, Host, Scheme, Port, Path, HTTP Method, HTTP Headers, Query, Body (Encoded-Form, JSON, plain-text)
Change the Response Content, including HTTP Status Code, HTTP Headers, and 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
3. How to use it?
You can access the Scripting Tool by:
Script Menu -> Script List (⌥⌘I)
Open Menu Context from Right Click on the Flow -> Tools -> Scripting
Please Check out Snippet Code to see a collection of snippet JS codes for the Scripting Tool.
4. Scripting with GraphQL Requests
From Proxyman 2.27.0+, the Scripting Tool can work with GraphQL Request by a specific QueryName. Please check out the following GraphQL Document.
GraphQL5. Examples
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
Make sure you enable SSL for this domain before creating the script)
Open the Scripting Tool and create a new Script Entry (⌘N). You can right-click on the Request -> Tools -> Scripting => Proxyman will create a Script too
Give the name and define a Matching Rule.
Ex: Name=Test on Localhost endpoint, URL=https://proxyman.io
Enable Run Script on Request and Response checkbox
Start writing JS code for
onRequest
function
onRequest(context, url, request) {}
onRequest() Object Format
context
, url
and request
objects are defined by:
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: Binary Data (application/zip, application/octet-stream)
Uint8Array
Check out common JS code from Snipped Code Page
Snippet Code7. Start writing code on onResponse
function
onResponse() Objects Format
context
, url
, request
, and response
objects are defined by:
You can change statusCode
, headers
and body
from the response Obj
If 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 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)
Uint8Array
You must return request
and response
object in onRequest
and onResponse
function
6. Built-in Addons and Libraries
Proxyman provides plenty of addons and libraries that help you achieve common tasks: Hashing, Encode/Decode, ...
AddonsBuilt-in JS LibrariesSnippet Code7. Debugging JS Error
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().
8. Use Scripting as a Mock API
From Proxyman 2.32.0, we can use the 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:
Open the Scripting Tool -> Select the Script
Enable Run as Mock API checkbox.
Then you can define a Response as usual:
9. Notes
You must return
request
andresponse
Object inonRequest
andonResponse
function.Proxyman 4.16.0 or later: Proxyman now converts the Binary Data to Uint8Array
Proxyman 4.15.0 or earlier: 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.
Last updated