Script mode for browser monitor configuration
In addition to the usual configuration in the UI, you can use Script mode to configure your clickpath or single-URL monitors. In this mode, you can access the underlying JSON script of your monitor. If you're a synthetic power user, this will make your life a lot easier and allow you to speed up clickpath creation and management. Use the script editor to quickly find specific events (steps), adapt locators across the whole script, or edit parts of the clickpath without rerecording.
You aren't limited to just one mode—you can switch back and forth between the UI and script modes by clicking the Clickpath/Script switch.
Access the clickpath script
To edit your clickpath browser monitor in script mode:
- Select Synthetic from the navigation menu.
- Select the clickpath monitor you want to edit.
- Click the Browse (...) button and select Edit.
- Click the Recorded clickpath tab in the Monitor settings menu on the left.
- Click Script at the top.
Access the single-URL script
To edit your single-URL browser monitor in the script mode:
- Select Synthetic from the navigation menu.
- Select the single-URL monitor you want to edit.
- Click the Browse (...) button and select Edit.
- Click the Monitor script tab in the in the Monitor settings menu on the left.
Edit the script
You can download the script, or just copy it from the editor, and edit it in a text editor of your choice.
However, you can also edit the script directly in the browser. This provides the following benefits:
- Autocomplete—just press
Ctrl
+Spacebar
to see the list of suggestions. - Syntax highlighting makes it easier for you to write script code.
- Instant error validation—the editor instantly shows a warning for any error in the script. Hover over the error to see what's wrong and a suggestion for how to fix it. You cannot save changes until the code is error free.
You can play your changes back for clickpath scripts without saving them—just click Play back clickpath.
Script structure
Main script object
Contains the monitor script.
Element | Type | Description | Required |
---|---|---|---|
configuration | ScriptConfig | The setup of the monitor | optional |
type | string | The type of monitor
Possible values are:
|
required |
version | string | Script version—use the 1.0 value here. |
required |
events | Array of:
navigateEvent interactionEvent javaScriptEvent selectOptionEvent cookieEvent keystrokesEvent |
Steps of the clickpath—the first step must always be of the navigate type.
Note that an event is not the same thing as an action—only events that trigger web requests are called actions, so your script might not have as many actions as events. Synthetic actions (similar to user actions for real user monitoring) hold the performance data collected during the playback of clickpath events. The actual JSON object of the event depends on its type:
|
required |
The ScriptConfig
object
Contains the setup of the monitor.
Element | Type | Description | Required |
---|---|---|---|
userAgent | string | The user agent of the request | optional |
device | customDevice
or predefinedDevice |
The emulated device of the monitor—holds either the parameters of the custom device or the name and orientation of the preconfigured device.
If not set, then the Desktop preconfigured device is used.
|
optional |
bandwidth | bandwidthOptions
or predefinedBandwidth |
The emulated network conditions of the monitor
If not set, then the full available bandwidth is used. |
optional |
requestHeaders | requestHeader[] | The list of HTTP headers to be sent with requests of the monitor | optional |
requestHeaderFilters | string[] | Limits the usage of request headers. Only requests matching the specified criteria will use headers from the requestHeaders element. |
optional |
cookies | requestCookie[] | List of cookies to be created for the monitor
These cookies are added before execution of the first step. |
optional |
The customDevice
object
Contains the emulated device of the monitor.
Element | Type | Description | Required |
---|---|---|---|
mobile | boolean | The flag of the mobile device
Set to true for mobile devices or false for a desktop or laptop.
|
required |
touchEnabled | boolean | The flag of the touchscreen
Set to true if the device uses touchscreen. In that case, use can set interaction event as tap .
|
required |
width | integer | The width of the screen in pixels
The maximum allowed width is 1920 .
|
required |
height | integer | The height of the screen in pixels
The maximum allowed height is 1080 .
|
required |
scaleFactor | integer | The pixel ratio of the device | optional |
The predefinedDevice
object
Contains one of the preconfigured device emulations.
Element | Type | Description | Required |
---|---|---|---|
deviceName | string | The name of the preconfigured device—when editing in the browser, press Crtl +Spacebar to see the list of available devices. |
required |
orientation | string | The orientation of the device—portrait or landscape
Desktop and laptop devices are not allowed to use the portrait orientation.
|
required |
The bandwidthOptions
object
Contains the emulated network conditions of the monitor.
Element | Type | Description | Required |
---|---|---|---|
latency | integer | The latency of the network, in milliseconds | required |
download | integer | The download speed of the network, in bytes per second | required |
upload | integer | The upload speed of the network, in bytes per second | required |
The predefinedBandwidth
object
Contains the pre-configured network emulations.
Element | Type | Description | Required |
---|---|---|---|
networkType | string | The type of the preconfigured network—when editing in the browser, press Crtl +Spacebar to see the list of available networks. |
required |
The requestHeader
object
Contains the list of HTTP headers to be sent with requests of the monitor.
The following headers are not allowed:
- user-agent
- cookie
Element | Type | Description | Required |
---|---|---|---|
name | string | The name of the HTTP header | required |
value | string | The value of the HTTP header | required |
The requestCookie
object
Contains the list of cookies to be created for the monitor.
Every cookie must be unique within the list. However, you can use the same cookie again in other event.
Element | Type | Description | Required |
---|---|---|---|
name | string | The name of the cookie
The following cookie names are now allowed:
|
required |
value | string | The value of the cookie—the following symbols are not allowed: ;,\" . |
required |
domain | string | The domain of the cookie | required |
path | string | The path to the cookie | optional |
The navigateEvent
object
Contains a Navigate event.
Element | Type | Description | Required |
---|---|---|---|
type | string | The type of synthetic event
In this case, the event type is navigate .
|
required |
url | string | The URL to navigate to | required |
description | string | A short description of the event to appear in the UI | required |
wait | waitCondition | The wait condition for the event—defines how long DESK should wait before the next action is executed. | optional |
validate | validationType[] | The validation rule for the event—helps you verify that your browser monitor loads the expected page content or page element. | optional |
target | targetType | The tab on which the page should open | optional |
authentication | authenticationType | The login credentials to bypass the browser login mask | optional |
The interactionEvent
object
Contains a Click or a Tap event.
Element | Type | Description | Required |
---|---|---|---|
type | string | The type of synthetic event
In this case, click or tap
|
required |
description | string | A short description of the event to appear in the UI | required |
button | integer | The mouse button to be used for the click | required |
wait | waitCondition | The wait condition for the event—defines how long DESK should wait before the next action is executed. | optional |
validate | validationType[] | The validation rule for the event—helps you verify that your browser monitor loads the expected page content or page element. | optional |
target | targetType | The element to click/tap on | optional |
The javaScriptEvent
object
Contains a JavaScript event.
Element | Type | Description | Required |
---|---|---|---|
type | string | The type of synthetic event
In this case, javascript
|
required |
description | string | A short description of the event to appear in the UI | required |
javaScript | string | The JavaScript code to be executed in this event | required |
wait | waitCondition | The wait condition for the event—defines how long DESK should wait before the next action is executed. | optional |
target | targetType | The tab where the JavaScript code is executed | optional |
The selectOptionEvent
object
Contains a Select option event.
Element | Type | Description | Required |
---|---|---|---|
type | string | The type of synthetic event
In this case, selectOption
|
required |
description | string | A short description of the event to appear in the UI | required |
selections | listOptions[] | The options to be selected | required |
wait | waitCondition | The wait condition for the event—defines how long DESK should wait before the next action is executed. | optional |
validate | validationType[] | The validation rule for the event—helps you to verify that your browser monitor loads the expected page content or page element. | optional |
target | targetType | The selection tag of the drop-down | optional |
The cookieEvent
object
Contains a Cookie event.
Element | Type | Description | Required |
---|---|---|---|
type | string | cookie |
required |
description | string | A short description of the event to appear in the UI | required |
cookies | requestCookie[] | The list of cookies to be created during the event
Every cookie must be unique within the list. However, you can use the same cookie again in other event. |
required |
The keystrokesEvent
object
Contains a Keystroke event.
Element | Type | Description | Required |
---|---|---|---|
type | string | keystrokes |
required |
description | string | A short description of the event to appear in the UI | required |
textValue | string | The text to enter | required |
masked | boolean | Indicates whether the textValue is encrypted (true ) or not (false ). |
required |
simulateBlurEvent | boolean | Defines whether to blur the text field when it loses focus.
Set to true to trigger the blur the textValue .
|
required |
wait | waitCondition | The wait condition for the event—defines how long DESK should wait before the next action is executed. | optional |
validate | validationType[] | The validation rule for the event—helps you to verify that your browser monitor loads the expected page content or page element. | optional |
target | targetType | The object to enter the text to | optional |
The waitCondition
object
Contains the wait condition for an event.
Element | Type | Description | Required |
---|---|---|---|
waitFor | string | The time to wait before the next event is triggered
Possible values are:
|
required |
milliseconds | integer | The time to wait, in milliseconds
The maximum allowed value is 60000 .
|
required for the time type
Not applicable otherwise |
timeoutInMilliseconds | integer | The maximum amount of time to wait for a certain element to appear, in milliseconds—if exceeded, the action is marked as failed.
The maximum allowed value is 60000 .
|
required for the validation type
Not applicable otherwise |
validation | validationType[] | The element to wait for | required for the validation type
Not applicable otherwise |
The validationType
object
Contains the validation rule for an event or waiting rule.
Element | Type | Description | Required |
---|---|---|---|
type | string | The goal of the validation:
|
required |
match | string | The content to look for on the page
Regular expressions are allowed. In that case set isRegex as true .
|
required for content_match
optional for element_match
|
isRegex | boolean | Defines whether match is a plain text (false ) or regular expression (true ). |
optional |
failIfFound | boolean | The condition of the validation:
|
required |
target | targetType | The element to look for on the page | required for element_match
optional for content_match
|
The authenticationType
object
The login credentials to bypass the browser login mask during a Navigate event
Element | Type | Description | Required |
---|---|---|---|
type | string | The type of authentication—basic or webform .
Only the basic type is allowed in clickpath monitors.
|
optional |
username | string | The username to log in with | required |
password | string | The password to log in with
It contains not the actual password, but a unique ID of it, and the password itself is stored in DESK and found by the ID. If you change the ID, the stored password becomes unavailable. To change the password, set the masked property as false and type in the new password.
|
required |
masked | boolean | The flag of the masked password
true means that the password is encrypted and stored, and the password field shows the ID of the password to encrypt the password.
Set false to type in a new password.
|
optional |
The listOptions
object
Contains the options to be selected in the Select option event.
Element | Type | Description | Required |
---|---|---|---|
index | integer | The index of the option to be selected | required |
value | string | The value of the option to be selected | required |
The targetType
object
Contains the target tab or element of the event.
Element | Type | Description | Required |
---|---|---|---|
window | string | The tab of the target | optional |
locators | locatorType[] | The list of locators identifying the desired element | optional |
The locatorType
object
Contains an element of a page to look for.
Element | Type | Description | Required |
---|---|---|---|
type | string | Defines where to look for the element:
|
required |
value | string | The name of the element to be found | required |
This is a model of the script JSON, showing all the possible elements. It has to be adjusted to be used as an actual script. To get an example of a real monitor, you can check the script of an existing monitor.
synthetic-script-model.json
{
"configuration": {
"userAgent": "string",
"device": {
"mobile": true,
"touchEnabled": true,
"width": 375,
"height": 667,
"scaleFactor": 2,
"deviceName": "string",
"orientation": "portrait"
},
"bandwidth": {
"latency": 1,
"download": 1,
"upload": 1,
"networkType": "WiFi"
},
"requestHeaders": [
{
"name": "string",
"value": "string"
}
],
"requestHeaderFilters": [
"string"
],
"cookies": [
{
"name": "string",
"value": "string",
"domain": "string",
"path": "string"
}
]
},
"version": "1.0",
"type": "clickpath",
"events": [
{
"type": "navigate",
"url": "string",
"description": "string",
"wait": {
"waitFor": "page_complete"
},
"authentication": {
"type": "basic",
"masked": true,
"username": "string",
"password": "string"
},
"validate": [
{
"type": "content_match",
"failIfFound": true,
"isRegex": false,
"match": "string"
}
],
"target": {
"window": "string"
},
},
{
"type": "click",
"description": "string",
"button": 0,
"wait": {
"waitFor": "network"
},
"target": {
"locators": [
{
"type": "css",
"value": "string"
},
{
"type": "dom",
"value": "string"
}
]
},
"validate": [
{
"type": "element_match",
"failIfFound": false,
"target": {
"locators": [
{
"type": "css",
"value": "string"
}
]
}
}
]
},
{
"type": "javascript",
"description": "string",
"javaScript": "string",
"wait": {
"waitFor": "time",
"milliseconds": 2000
},
"target": {
"window": "string"
}
},
{
"type": "selectOption",
"description": "string",
"selections": [
{
"index": 1,
"value": "string"
}
],
"wait": {
"waitFor": "validation",
"validation": {
"type": "element_match",
"failIfFound": false,
"match": "string",
"target": {
"locators": [
{
"type": "dom",
"value": "string"
}
]
}
},
"timeoutInMilliseconds": 60000
}
},
{
"type": "cookie",
"description": "string",
"cookies": [
{
"name": "string",
"value": "string",
"domain": "string",
"path": "string"
}
]
},
{
"type": "keystrokes",
"description": "string",
"textValue": "string",
"masked": false,
"simulateBlurEvent": true,
"wait": {
"waitFor": "next_action"
},
}
]
}