Transaction Commands and Macros

This article contains a subset of transaction commands and macros to assist with scripting needs. Check back often as the list continues to expand.

Request Commands

open

Syntax: open("url")
Purpose: To open a specified url. This command is always used at the beginning of the transaction test.
Explanation: The parameter is only to provide the specific URL. Use this at the beginning of the transaction or anytime you want to open a specific url. This will create a new step.
Example: open("http://www.example.com")
Supported Monitors: emulated, Chrome, Mobile, API

openWhile

Syntax: openWhile("<URL>", "${extract('<resp-header|resp-content(default)>','<regexp with extraction>', {'optional-chained-sub-macros'})}")
Purpose: Used in API Monitoring when the API client must submit a job to an API and it requires some time to be processed. The API client must continue to poll an API end point until its response states the job is complete. To handle such use case you must use a new verb, "openWhile", which will keep opening the specified URL until a specified condition is met.
Explanation: The 1st parameter is the URL to navigate. The 2nd parameter should contain one or more sub-macros (either "${extract(..)}" or "${extractVariable(.)}") upon which to validate the continuation of the step.
Example:openWhile("${extractVariable('saved_url')}", "${extract('respheader','regexp:HTTP/1\.[01]\s+(\d+)','nequals(200)')}")

setHeader

Syntax: setHeader(header-key, value)
Purpose: Used for dynamically assigning a particular HTTP request header for either the root-request (when no child-request-pattern is used) or child-requests (if the child-request-pattern is used).
Explanation: The 1st parameter specifies the header-key and optional child-request-pattern (separated by a colon ":"). The 2nd parameter the header-value.
Example: open(www.example.com)

setHeader('Content-Type', 'text/xml')
//Child-Request example
setheader('request-override:http://www.childrequest.com', 'http://www.newrequest.com')
//Adding Cookies to redirects
setHeader Cookie:domain.com key=value

setHeaderAll

Syntax: setHeaderAll(headerKey, headerValue)
Purpose: Same as "setHeader", except it will apply to all steps of a transaction. It dynamically assigns a particular HTTP request header for either the root-request (when no child-request pattern is used) or child-request (if child-request pattern is used) for all steps of a transaction.
Explanation: It is a Catchpoint custom metrics. The 1st parameter specifies the header-key and optional child-request-pattern (separated by a colon ":"). The 2nd parameter is the header-value.
Example:

open([www.example.com)](http://www.example.com/)
setHeaderAll('Content-Type', 'text/xml')

setNavigatePostData

Syntax: setNavigatePostData(postData)
Purpose: it dynamically send POST data to the root request.
Explanation: It is a Catchpoint custom metric. Using web test with emulated monitor or API test, we can dynamically ask our agent to POST the data to the root request. The ability to post for Chrome is not yet available. Instead, we append to the query string of a given associated step's "open" URL.
Example:

open([www.example.com](http://www.example.com/))
setNavigatePostData("dataset")

Supported Monitors: Chrome, emulated, API

Click Commands**

Click

Syntax: click(locator <string> <required>)
Purpose: To select or interact with an element on a page.
Explanation: Simulates a mouse click at the specific location entered.
Example: click("//*[@id="broadcast-meta")
Supported Monitors: emulated, Chrome, Mobile

clickAndWait

Syntax: clickAndWait(locator <string> <required>)
Purpose: This action tells the agent to perform a click action on the specified element. Immediately following the click action, the agent will create a new step and therefore wait for an onLoad event (document complete) to occur.
Explanation: The only parameter for this action is a locator string. The agent will perform a click action on the element found at the locator and will result in a new step created.
Example: clickAndWait("//*[@id='foo']")

clickAt

Syntax: clickAt(locator, coordString)
Purpose: Simulates a mouse click at the specific location entered.
Explanation: locator- an element locator. coordString: Specifies the x,y position of the mouse event
Example: clickAt("//li[@id='tab-panel-id__second-tab-id' ","0,0")
Supported Monitors: Chrome, Mobile

clickMouse

Syntax: clickMouse(locator)
Purpose: To select or interact with an element on a page.
Explanation: clickMouse() is similar to click(), but clickMouse() fires more mouse trigger events. The clickMouse() command is more likely to trigger any attached JavaScript.
Example: clickMouse("//*[@id="broadcast-meta")
Supported Monitors: Chrome, Mobile

Note: In case of the following scenario, Clickmouse verb may not work as expected:

When you use clickMouse verb to click on an object that is below the fold of a page and
When you are testing on Chrome version 66 or greater

Workaround: Please consider using Click command or using <https://docs.catchpoint.com/docs/transaction-commands-and-macros#runScript" target="_blank" rel="noopener">runScript command

clickMouseAndWait

Syntax: clickMouseAndWait(locator <string> <required>)
Purpose: This action tells the agent to perform a click mouse action on the specified element. Immediately following the click action, the agent will create a new step and therefore wait for an onLoad event (document complete) to occur. This command differs from clickAndWait as it triggers JavaScript on the page in most cases where clickAndWait will not.
Explanation: The only parameter for this action is a locator string. The agent will perform a click action on the element found at the locator. This command is used in place of clickAndWait if the test is failing due to the clickAndWait command not executing the expected JavaScript.
Example: clickMouseAndWait( "//*[@id='foo']")

Note: In case of the following scenario, Clickmouse verb may not work as expected:

When you use clickMouse verb to click on an object that is below the fold of a page and
When you are testing on Chrome version 66 or greater

Workaround: Please consider using Click command or using runScript command

Page Load

Note: - For all the wait commands If there is no activity on the network during the specified wait time, the logic that is applied by the system is to only display the time up to which there was some request/network activity on the wire. To be more specific, we only look at the network events and not the JavaScript events. So for example, if the specified wait time is 5000 ms. But all the network activity was complete within 3000 ms, then the 3000ms is what will appear in the waterfall/test time.

waitForElementPresent

Syntax: waitForElementPresent(locator <string> <required>, timeValue <integer><optional>)
Purpose: This action tells the agent to wait for the specified locator to be present on the page before continuing onto the next action. The optional second timeValue parameter can range from 50-30000 ms. The default, if not specified, is 20000 ms.
Explanation: The 1st parameter is used for specifying the element locator that you wish to wait for to be present on the page. The second parameter is optional and is used to specify an amount of time that the test should wait for the locator to be present. Once the element is present on the page, the agent will continue onto the next command, if the element is not present by the specified amount of time, the test will fail.
Example: waitForElementPresent("//*[@id='foo']", "30000")

waitForNoRequest

Syntax: waitForNoRequest(waitTime<integer> <required>)
Purpose: This action tells the agent to wait for the specified amount of time for no HTTP requests to be on the network before continuing onto the next command. The waitTime parameter can range between 1000-5000 ms.
Explanation: The only parameter for this action is a waitTime. The agent will wait for that specified amount of time before moving onto the next step/command. Which will, in return, allow necessary requests more time to load after document complete.
For instance, when you add waitforNoRequest(5000), initially agent waits 5000 ms after doc complete for any network activity. During that period if there is any network activity, then the agent waits another 5000 ms for the next network activity to end and the process goes on until no other request loads within the specified timeframe(5000 ms) as shown in the waterfall below:

Example: waitForNoRequest("2000")

waitForTextPresent

Syntax: waitForTextPresent(String <required>, timeValue <integer> <optional>)
Purpose: This action tells the agent to wait for the specified text to be present on the page before continuing onto the next action. The optional second timeValue parameter can range from 50-30000 ms. The default, if not specified, is 20000 ms.
Explanation: The 1st parameter is used for specifying the text that you wish to wait for to be present on the page. The second parameter is optional and is used to specify an amount of time that the test should wait for the locator to be present. Once the text is present on the page, the agent will continue onto the next command, if the text is not present by the specified amount of time, the test will fail.
Example: waitForTextPresent("FooBar", "30000")

waitForUrl

Syntax: waitForUrl(pattern <string> <required>, timeValue <integer> <optional>)
Purpose: This action tells the agent to wait for the specified URL to be loaded in the waterfall graph, before continuing onto the next action. The parameter specifies the Regular Expression pattern, upon which to wait for a matching completed request's URL, before proceeding with the transaction. By default the waits 20000ms, this can be increased to 30000ms.
Explanation: This will cause the transaction to wait for up to the given #-of-msec, for a particular request URL to have been completed. The 1st parameter is used for specifying the object URL that you wish to wait for on the page. The second parameter is optional and is used to specify an amount of time that the test should wait for the locator to be present. Once the URL is loaded in the waterfall graph, the agent will continue onto the next command, if the URL is not loaded in the specified amount of time, then the test will fail.
*Please make sure that you escape the special characters as shown below.
Example: waitForUrl("www.example.com", "30000")

waitForVisible

Syntax: waitForVisible(locator)
Purpose: To wait until the locator appears on the page
Explanation: This action tells the agent to wait until the locator is visible on the page. If the locator is never visible, the test will continue waiting until timing out.
Example: waitForVisible("//*[@id='column-two']")

pause

Syntax: pause(waitTime)
Purpose: This action tells the agent to pause for a set amount of time. The pause's wait time parameter can range between 100 to 30,000 ms.
Explanation: This command is used when the agent needs to wait for a set amount of time and this is not impacted by the way the requests are loaded before proceeding to the next step or command. Only a parameter is required for this action.
*This pause time will not be added to webpage response, but will be added to overall test timeout threshold*
Example: pause("5000")
Supported Monitors: emulated, Chrome, Mobile.

Variable Commands

storeGlobalVariable

StoreGlobalVariable
Syntax: storeGlobalVariable(<macros>,<name>)
Purpose: This transaction verb is used to store the variable data globally, and this data can be used later on via the "${globalVariable(.)}" macro.
Naming Limitation: 32 character limit.
Explanation: The first parameter is used for getting the value to store, obtained via one or more macros (either "${extract(.)}" or "${extractVariable(.)}"). The second parameter is used for setting the name of the stored global variable.
Example: In the example below, a cookie is retrieved from the response headers and stored as a variable named newCookie. The Global Variable is then retrieved and set as a new cookie in one or more tests:

//Set Global Variable
open("http://www.google.com")
storeGlobalVariable("${extract(resp-header, regexp:set-cookie: (.*))}", "newCookie")

//Get Global Variable
open("http://www.google.com")
setHeader("Cookie", "${globalVariable(newCookie)}")

storeScriptVariable

Syntax: storeScriptVariable(name, script)
Purpose: This transaction verb is used to store the data or value returned from executed JavaScript into a Selenium variable. This is only available on the Edge and Chrome monitors.
Explanation: The storeScriptVariable() should only execute JavaScript functions that have been defined on the page or have been injected with the runScript() command.
Example: In this example, the following actions occur: Open a page to execute JS on a URL, create a JS function that returns 'point', create a variable that concatenates strings, and then stores the JS data into Selenium variable.

open("http://www.google.com")
runScript("function bar(){return 'point';}")
runScript("var foo='catch' + bar();")
storeScriptVariable("foobar","foo;")

For additional information see the Store JavaScript Variable and Data for Use in a Transaction Test KB.

storeVariable

Syntax: storeVariable (macros, VariableName)
Purpose: This transaction verb is used for storing data in a temporary transaction variable which can later be used by the "${extractVariable(.)}" macro.
Explanation: The first parameter is used to get the value to store, obtained via one or more macros (either "${extract(.)}" or "${extractVariable(.)}"). The second parameter is used for setting the name of the stored variable.
Example: In this example, a cookie value is passed from one step to another. The cookie can be extracted from the header, stored as a variable, and then retrieved later on in the test. Please see the code for this below:

open(http://www.google.com)
StoreVariable("${Extract(resp-header, regexp:set-cookie:(.*))}", "cookie")

open(http://www.google.com)
setheader("Cookie", "${extractVariable(cookie)}")

NOTE: var=${} is a different way to store a variable within scripts. Please note that it can cause syntax error warnings in the script editor.

Trigger Events

fireEvent

Syntax fireEvent("xpath","event listener")
Purpose: This is used when a regular selenium command is not working. Instead, you may need to trigger an event listener and this fireEvent() command can be used to ensure that the event listener is fired correctly. Usually this command is better when using JS framework such as extJS and GWT where click command doesn't work very well because it does not trigger the MouseUp event.
Explanation: The first parameter is the xpath and the 2^nd parameter is the event listener command. You can even add and Wait at the end of the command to create a new step.
Example : fireEvent("//*[@class="codeail"]", "change")

focus

Syntax: focus(locator)
Purpose: Have the agent focus to the specified element. It can also be used to scroll to an element in a transaction test.
Explanation: Before executing certain commands such as type or keypress, you may need to use this command to allow the agent focus on the specified element. For example, if the element is an input field, the command focus will move the cursor to that field.
Example: focus(//input[@id='username'])
Supported Monitors: emulated, Chrome, Mobile

keyDown

Syntax: keyDown(locator, ASCII code)
Purpose: Have the agent simulate as if a user is pressing the key down to the specified element.
Explanation: Simulates when a user is pressing a key. Generally, this command is used with keyUp command.
Example: keydown("//*[id='submit']", "32") //Presses the space key at the submit ID.
Supported Monitors: emulated, Chrome, Mobile.

keyPress

Syntax: keyPress(locator, ASCII)
Purpose: Useful when you want to press keyboard keys such as "enter" key, "up-down arrows" keys, "backspace" key.
Explanation: Simulates when a user is pressing a key and releases it for the targeted element. The ASCII value of the keyboard key is needed in the value column.
Example: keypress("//*[id='submit']", "13") //Presses the enter key at the submit ID.
Supported Monitors: emulated, Chrome, Mobile.

keyUp

Syntax: keyUp(locator, ASCII code )
Purpose: Have the agent simulate as if a user is pressing the key up to the specified element.
Explanation: Simulates when a user is letting go of a key. Generally, this command is used with keyDown command.
Example: keyup("//*[id='submit']", "32") //Presses the space key at the submit ID.
Supported Monitors: emulated, Chrome, Mobile.

shiftKeyDown

Syntax: shiftKeyDown()
Purpose: shiftKeyDown() presses the Shift key of the keyboard and is not released until the "shiftKeyUp" command executes.
Explanation: shiftKeyDown() does not take any parameter and is exactly like pressing the Shift Key as the name explains. It can be helpful when there is a need to type with capital letters.
Example:

Open([www.example.com](http://www.example.com/))`
shiftKeyDown()
type("xPath", "text")

Supported Monitors: Chrome, Mobile

shiftKeyUp

Syntax: shiftKeyUp()
Purpose: To release the pressed "Shift" key through "shiftKeyDown".
Explanation: shiftKeyUp() works in conjunction with shiftKeyDown() command. shiftKeyDown() commands presses the Shift key and the key only gets released with the shiftKeyUp() command
Example:

open([www.example.com](http://www.example.com/))
shiftKeyDown()
type("xPath", "text")
shiftKeyUp()

Supported Monitors: Chrome, Mobile

type

type(locator, value)
Syntax: type(locator <element> <required>, value <string> <required>)
Purpose: Simulates each keystroke at the locator.
Explanation: Simulates keystroke on the specified element, as though you typed the value key-by-key.
Example: type("//*[@name='q']", "catchpoint")

typeKeys

typeKeys(locator, value)
Syntax: typeKeys(locator <element> <required>, value <string> <required>)
Purpose: Simulates each keystroke. So if the page has an action that occurs as you type (for example, google's autosuggest), this will be the action you would need.
Explanation: Simulates keystroke events on the specified element, as though you typed the value key-by-key. This is a convenience method for calling keyDown, keyUp, keyPress for every character in the specified string; this is useful for dynamic User Interface widgets (like auto-completing combo boxes) that require explicit key events.
Example: typeKeys("//*[@name='q']", "catchpoint")

typeKeysAndWait

typeKeysAndWait(locator, value)
Syntax: typeKeysAndWait(locator <element> <required>, value <string> <required>)
Purpose: Useful when entered value triggers AJAX call and needs to wait until server returns the response.
Explanation: After simulation of each key, it waits for the browser to complete the network calls, before moving on to the next action and has the same functionalities as typeKeys.
Example: typeKeysAndWait("//*[@name='q']", "catchpoint")

mouseOver

Syntax: mouseOver("<locator>")
Purpose: This action tells the agent to perform a mouseover action on the specified element.
Explanation: This command triggers a js event on the specified element unlike actually moving the mouse cursor and hence we won't actually see it in the screenshots.
Example: mouseOver("(//*[@class='_1QZ6fC _3Lgyp8'])[6]")

Assert Commands

assert

Syntax: assert(extraction)
Purpose: To verify that the extraction is present in the transaction test.
Explanation: A Selenium command that is used to verify the extraction appears on the test. If it is not present, the test will fail. To have the test assert a specific object in the test, its possible to also use other macros that are part of the assert family such as assertText or assertElementPresent.
The assert command can also be used for asserting "HTTPS" and redirection codes.
Example: assert(false)

Use case 1:

open(www.google.com)
var foo = 9
assert(${var(foo, eq(10))})

This will fail since 9 does not equal 10.

Use case 2:
To assert that a site uses HTTPS, use the following script. The assert will fail the test if the site does not use HTTPS at any request.

open(www.google.com)
var test = ${extractChild("url","regexp:(https)\://")};
assert("${switch(${var(test)}, 'https',true,false)}")

To assert a redirect code, use the following script:

open(www.yahoo.com)
var a = ${Extract("resp-header","regexp:HTTP/1\.1 (.*) Redirect")}
assert(${var(a,eq('301'))})
open("www.${var(a)}.com")

Supported Monitors: emulated, Chrome, Mobile, API

assertBodyText

Syntax: assertBodyText("pattern")
Purpose: Assertion to ensure a particular text string is present on the body of the base page HTML.
Explanation: This command is used to make sure a text string appears in the HTML body. If this command's condition is not met (i.e. the text string is not present in the HTML body), then the test will fail and cease to execute further commands.
Example:assertBodyText("<li title="Catchpoint Help"></li>")
Supported Monitors: Chrome, Mobile

assertChecked

Syntax: assertChecked("locator")
Purpose: To assert that a particular checkbox or radio button is checked.
Explanation: This command is used to make sure a checkbox or radio button is checked. If this command's condition is not met (i.e. the locator is not checked), then the test will fail and cease to execute further commands.
Example: assertChecked("//button[@id="check"]")
Supported Monitors: Chrome, Mobile.

assertElementPresent

Syntax: assertElementPresent(locator)
Purpose: To verify a particular locator to be present on a targeted page element.
Explanation: This command is used to make sure an expected element locator appears during the transaction test. If this command's condition is not met (i.e. the element locator is not present), then the test will fail and cease to execute further commands.
Example: assertElementPresent("//*[@class="foo"]")

assertElementNotPresent

Syntax: assertElementNotPresent(locator)
Purpose: To verify a particular locator to be not present on a targeted page element.
Explanation: This command is used to make sure an unexpected element locator does not appear during the transaction test. If this command's condition is met (i.e. the element locator is present), then the test will fail and cease to execute further commands.
Example: assertElementNotPresent("//*[@class="foo"]")

assertNotBodyText

Syntax: assertNotBodyText("pattern")
Purpose: Assertion to ensure a particular text string is not present on the body of the base page HTML.
Explanation: This command is used to make sure a text string does not appear in the HTML body. If this command's condition is not met (i.e. the text string is present in the HTML body), then the test will fail and cease to execute further commands.
Example: assertNotBodyText("<li title="Catchpoint Help"></li>")
Supported Monitors: Chrome, Mobile

assertNotChecked

Syntax: assertNotChecked("locator")
Purpose: To assert that a particular check box or radio button is not checked.
Explanation: This command is used to make sure a check box or radio button is not checked. If this command's condition is not met (i.e. the locator is checked), then the test will fail and cease to execute further commands.
Example: assertNotChecked("//button[@id="nocheck"]")
Supported Monitors: Chrome, Mobile

assertNotText

Syntax: assertNotText("locator", "pattern")
Purpose: To verify that a particular text string is not present on a targeted page element.
Explanation: This command is used to make sure unexpected text does not appear during your transaction test. If this command's condition is not met, then the test will fail and cease to execute further commands.
Example: assertNotText("//*[@id="error-dialog"], "Payment successful")
Supported Monitors: Chrome, Mobile

assertText

Syntax: assertText("locator", "pattern")
Purpose: To verify a particular text string is present on a targeted page element
Explanation: This command is used to make sure an expected text string appears during the transaction test. If this command's condition is not met (i.e. the text string is not present), then the test will fail and cease to execute further commands.
Example: assertText("//*[@id="main-menu"], "home")
Supported Monitors: Chrome, Mobile

assertTextNotPresent

Syntax: assertTextNotPresent("pattern")
Purpose: Assertion to ensure a particular text string is not present on the page
Explanation: This command is used to make sure an unexpected text string does not appear during your transaction test. If this command's condition is not met (i.e. the text string is present anywhere on the page), then the test will fail and cease to execute further commands.
Example: assertTextNotPresent("404")
Supported Monitors: Chrome, Mobile

assertTextPresent

assertTextPresent
Syntax: assertTextPresent(<string>)
Purpose: To check if the page loaded contains a specific text to ensure it is the expected page
Explanation: This action tells the agent search the text of a page for a specific string, and if the condition is not met, the transaction test will fail.
Example: assertTextPresent ("signed in")

assertTitle

Syntax: assertTitle(pattern)
Purpose: To check if the page loaded contains a specific title to ensure it is the expected page.
Explanation: The action tells the agent to search the title of the page. If the titles are different, the test will fail.
Example: assertTitle("Yahoo")
Supported Monitors: Chrome, Mobile.

assertValue

Syntax: assertValue(locator, pattern)
Purpose: To check the location on a page loads the value specified.
Explanation: The action tells the agent to search the location and value of an object on a page. If the condition is not met, the transaction test will fail.
Example: assertValue("//input[@id=countrySelect]", "Switzerland")
Supported Monitors: Chrome, Mobile

assertVisible

Syntax: assertVisible(locator)
Purpose: To check if the page loaded contains a specific object.
Explanation: The action tells the agent to search the location of an object on a page. If the condition is not met, the transaction test will fail.
Example: assertVisible("//input[@id=countrySelect]")
Supported Monitors: Chrome, Mobile

assertHttpResponseCode

Syntax: assertHttpResponseCode("value")
Purpose: Validates the root-request's response-code.
Example: assertHttpResponseCode("200")
Supported Monitors: Chrome, Emulated

assertHtmlSource

Syntax: assertHtmlSource("value")
Purpose: It is used to assert the response content regardless of a content type.
Example: assertHtmlSource("Catchpoint")
Supported Monitors: Chrome, Emulated

Others

select

Syntax: select("locator","Index")
Purpose: This command is particularly used to select an option from the dropdown.
Explanation: The select command is used to select the option 'locator' from the dropdown field named: subfolder. The select command takes two arguments, first is the locator of the field that holds the dropdown. The second argument is the value of the desired drop-down option.
Example: select("//select[@name='subFolderName']","value=EngRvwReq")
**Supported Monitors: **IE, Chrome, Mobile

check

Syntax: check(locator)
Purpose: Check a toggle-button on a page.
Explanation: Will fire the check event for the toggle-button
Example: check("//*[@id="programming"]")
Supported Monitors: Chrome, Mobile

dynamicStepOnNewPage

Syntax: dynamicStepOnNewPage("dynamicStepFunctionalityToggle")
Purpose: "dynamicStepOnNewPage 1", is in place for when the agent recognizes that the browser navigated dynamically to a new page, which could be caused by a META refresh tag or Javascript execution. Usage, in this case, is the same.
Explanation: This is used to allow the dynamic creation of a new step when a new page is detected (based on the "OnUnload" DOM event occurring). The verb spans across the entire transaction, so it needn't be repeated for each step where dynamic step creation is desired. Note: It should be deactivated where it no longer is desired. The parameter must be set to a value of "1" to activate dynamic-step functionality. Otherwise, it will deactivate dynamic-step functionality.
Example:

dynamicStepOnNewPage
setStepName("Please Wait")

Supported Monitors: IE

ignoreDocComplete

Syntax: IgnoreDocComplete
Purpose: Ignores Document Complete when a page is loading. This is particularly useful on transaction steps which start with AJAX activity.
Explanation: This command is useful when a new step is created and the page will not have Document Complete such as pages that use AJAX. There are no parameters
Example: IgnoreDocComplete
Supported Monitors: emulated, Chrome, Mobile

runScript

Syntax: runScript(script)
Purpose: To execute javascript function.
Explanation: There are different ways to use this command, from simply executing a javascript function to storing a variable
Example: Instead of using click(//*[@id="example"]), we can use:

Runscript($('#example').click())
Runscript(document.getElementById('example').click();)

setIndicator

Syntax: setIndicator(token, "${extract or var} macro")
Purpose: It sets an indicator for the current test.
Explanation: This verb allows the user to directly set an existing Insight Indicator with data from within a transaction test. The indicator's format (regex) setting will be ignored and not be applied to the value. The numeric data from the indicator can also be graphed.
The token can be set within the insight settings.
If the value for the insight is being set programmatically in the transaction script, the regular expression will be used to extract the value. For example, if a number is required to be extracted, a regular expression is still needed to be specified in the format field to extract it and as insight.
Example:

open([www.example.com](http://www.example.com/))
var abc = ${Extract('resp-header','regexp:HTTP(.*)')}
setIndicator(tokenEx,${Var(abc)})

Supported Monitors: Chrome, Mobile

setInnerHtml

Syntax: setInnerHtml(locator, inner Html)
Purpose: It dynamically assigns the value for innerHtml (it can be the text or any HTML code between the opening tag and closing tag of the element) to the element specified in "locator" using xPath.
Explanation: It is a Catchpoint custom metric. The 1st parameter specifies the element locator. The 2nd parameter specifies the "innerHtml" to assign to the located element.
Example:

open([www.example.com](http://www.example.com/))
setInnerHtml("xPath", "content in HTML format")

Supported Monitors: Chrome, Mobile

setInnerText

Syntax: setInnerText(locator, innerText)
Purpose: Is the same as setInnerHtml command. However, it dynamically assigns the value for innerText (content as plain text between the opening and closing tag) to the element specified in "locator" using xPath.
Explanation: It is a Catchpoint custom metric. The 1st parameter specifies the element locator. The 2nd parameter specifies the "innerText" to assign to the located element.
Example:

open([www.example.com](http://www.example.com/)) 
setInnerText("xPath", "content in plain text")

Supported Monitors: Chrome, Mobile

setResponseCode

Syntax: setResponseCode(Response_Code, child_request_url)
Purpose: Set the response code of the primary URL or Child Request URL
Explanation: This verb can be used to manipulate the response code of the test URL or a particular child request on the page.
Example:
For Primary URL:

open([www.example.com](http://www.example.com/))
setResponseCode("404")

For Child Requests:

open([www.example.com](http://www.example.com/))
setResponseCode("404", "child-request.example.com")

Supported Monitors: Chrome

setSpeed

Syntax: setSpeed(value)
Purpose: The setSpeed(value) command controls the speed of commands execution
Explanation: Using this command, the delay time between the execution of all commands within the step can be specified. By default, there is no delay in execution but the functionality allows specifying up to 5000ms. Please note the value is always in milliseconds.
Example: setSpeed(3000)
Supported Monitors: Chrome, Mobile

setStepName

Syntax: setStepName(name)
Purpose: To assign names to each step a transaction creates
Explanation: It is a custom Catchpoint metric. Using this command provides the ability to name transaction steps. This makes reading charts and waterfalls easier. In transactions, a new step starts whenever a new page is loaded. By default, steps are named using the following convention, "Step - 1", "Step - 2", "Step - 3", and so on.
Example:

//step 1
open(www.example.com)
setStepName("Step 1 Com Site")

Supported Monitors: Chrome, Mobile, emulated

setTracepoint

Syntax: setTracepoint(token, "${extract or var} macro")
Purpose: It sets a tracepoint for the current test.
Explanation: This verb allows the user to directly set an existing Insight Tracepoint with data from within a transaction test. The tracepoint's format (regex) setting will be ignored and not be applied to the value.
The token can be set within the insight settings.
Example:

open([www.example.com](http://www.example.com/))
var abc = ${Extract('resp-header','regexp:HTTP(.*)')}
setTracepoint(tokenEx,${Var(abc)})

Supported Monitors: Chrome, Mobile

Time macro Ref() Sub-Macro picking up an incorrect value

If there is a commented out line, the ref(x) sub-macro takes the value which is referred to in that commented out macro.
For example:

//var boo = ${Time(DD/MM/YY,44,44)}
var foo = ${Time(DD/MM/YY,1,1)}
var date = ${Time(DD/MM/YY,ref(0)+7)}
open("[http://www.google.com/${extractVariable('date')}](http://www.google.com/%24%7bextractVariable('date')%7d)")

Line 1 is commented out, but the 'ref(0)' statement in line 3 still considers the Time value from line 1.
If this behavior is encountered, be sure to either remove the commented line or move the line below the ref(x) call.

verifyTextPresent

Syntax: verifyTextPresent(pattern)
Purpose: To verify if the page loaded contains a specific text
Explanation: This action tells the agent to search the text of a page for a specific string, and if the condition is not met, nothing will happen, the script will continue.
Example: verifyTextPresent("signed in")

uploadFile

Syntax: uploadFile(locator, file)
Purpose: To upload a file in a transaction script.
Explanation: This command is used for webpage testing which also involves uploading specific files. The locator must be an <input> of type="file".
Example:

//Step-1
open("https://filebin.net/")
waitForNoRequest("2000")
uploadFile("//*[@id='fileField']", "Testfile.png")
fireEvent("//*[@id='fileField']", "change")

Supported Monitors: Chrome
Note: This command can be used in sheduled tests only. And can upload Max filesize of 2 MB.

stopTest

Syntax: stopTest(boolean)
Purpose: To stop the test in a specific step or line. This command is used where you would like the test to stop.
Explanation: This command is used to stop the test in a specific step or line during the transaction test. If this command's condition is not met, then the test will continue with the next steps or lines i.e., present in the transaction script.
Example:

//Step-1
open(www.google.com)
stopTest(true)

//Step-2
open(www.yahoo.com)

Supported Monitors: Chrome, Mobile

Macros

${AltKeyDown} and ${AltKeyUp}

Syntax: ${AltKeyDown} and ${AltKeyUp}
Purpose: To press the altKey down and then release it
Explanation: These macros allow you to press the altKey down, run any appropriate command which requires the altKey to be pressed, and then release after. These are used stand alone with no parameters.
Supported Monitors: Chrome, Mobile

${Base64}

Syntax: ${Base64("<content to encode>")}
Purpose: Some APIs require content to be encoded, this macro will encode the content in Base64 format.
Explanation: The agent will Base64 encode content which can then be posted as required.
Example: In this example, we will encode the text "this is a test message": Base64("this is a test message").
Supported Monitors: API, Transaction

${ExtractChild}

Syntax:

${ExtractChild('<source-type>', '<reg-exp-with-group>', '<optional, sub-macros>', '<optional, final-extraction-source-type>', '<optional, final-extraction-reg-exp-with-group>', '<optional, final-extraction-sub-macros>')}

Purpose:  To obtain information from actual content of a child request for use within a transaction script
Explanation: source-type:  Can be one of the following values (with the optional “-reverse” suffix to traverse redirections from the last redirection to the first)

req-header(request headers)
resp-content (response content)
resp-header (response headers)
url (some specific url)
reg-exp-with-group:  Used for extracting a value from the given source-type.
sub-macros:  Optional, used for modifying the extracted value.
final-extraction-source-type:  Optional, used only if the “sub-macros” value winds up equaling “true”.
final-reg-exp-with-group:  Optional, used for extracting a value from the given “final-extraction-source-type”.
final-extract-sub-macros:  Optional, used for modifying the “final-reg-exp-with-group”.

Example:

${ExtractChild("resp-header", "regexp:^Content-Length:\s*(\d+)"}

Supported Monitors: IE, Chrome, emulated, and Mobile.

${ExtractVariable}

Syntax: ${ExtractVariable(name <string> <required>)}
Purpose: This action extracts an already stored variable for use within the transaction test. It can be assigned via the "Var" modifier, or the "StoreVariable" command.
Explanation: Used for extracting variables within transaction tests. The synonym of this macro is ${Var()}.
Example: ${ExtractVariable(foo)}

${Extract}

Syntax: ${Extract(‘respType’, ‘regExp’)}
Purpose:  To obtain information from actual content of head request for use within a transaction script. It works with API tests also.
Explanation: respType:  Can be one of the following values:

req-header (request headers)
resp-content (response content)
resp-header (response headers)

**regExp: ** Regular expression used for obtaining value from the given source-type.
Example:

 ${Extract('req-header','regexp:HTTP.(\d\.\d)')}

Supported Monitors: IE, Chrome, emulated.
Multiline Capability: Add a parameter called "multiline" to indicate the extraction is multiline. If the regex in the extract matches characters spanning multiple lines, it will capture those characters in the extraction. This capability is currently not supported in Chrome.
Example:

 ${Extract('resp-content', 'regexp:(.*\n)', 'multiline')}

${GlobalVariable}

Syntax: ${GlobalVariable(name)}
Purpose: Variable to be used across tests. Useful when you are trying to use a variable in more than one test.
Explanation: This can only be used after doing StoreGlobalVariable. If the global variable is not set, this macro will return nothing and it will not cause a failure.
Example:

StoreGlobalVariable("${Extract('req-header','regexp:HTTP.(\d\.\d)')}", "foo")
${GlobalVariable(foo)}

Supported Monitors: emulated, Chrome, Mobile, API

${Hash}

${Hash(algorithm, data)}
Syntax: ${Hash(algorithm <algorithm> <name>, data <string> <required>)}
Purpose: This is used to hashify given data based on specified algorithm.[IE only]
Explanation: Returns the hashified data. Takes up to 3 parameters, where the 1st specifies the hash algorithm (default=md5, choices are: md5, ripcoded160, sha1, sha256, sha384, sha512), and the 2nd parameter is the data to hashify. The 3rd parameter is optional, whereby if used, will add a HMAC secret to the hash algorithm.
Example:

${Hash("sha512", "catchpoint")}

${HostRequestAuthority}

Syntax: ${hostrequestauthority}
Purpose: This returns host + possible port number. It is used to rewrite a URL completely and append an extra value to it.
Explanation: Obtains the given request URL's authority. This is the host or IP plus port number if the port is non-standard.
Example:

open(www.example.com)
setHeader(request-override: www.google-analytics.com/, ${hostrequestauthority}/path)

Supported Monitors: Chrome

${HostRequestPath}

Syntax: ${hostrequestpath}
Purpose: Returns the host request path. It is used to rewrite a URL completely and append an extra value to it
Explanation: Returns the HTTP request's path, for child-request overrides only.
Example:

open(www.site.com)
setHeader('request-override: www.google-analytics.com/', 'www.site.com/${hostrequestpath}')

Supported Monitors: Chrome

${If}

Syntax: If(case1, value1, case2, value2, case3, value3, case4, value4... ,caseN ,valueN, valueX)
Purpose: The if-then-else is used to cycle through various cases, and produce a value depending on the case, if the value can't be found then it will present an "else" value.
Example: In this example, we pick a random number between 1 and 10, if it is greater than 5 then it presents a value of domain1, if less then 4 then domain2, anything else, domain3.

var rand = ${random(1,10)};
var domain = ${If(${"var(rand)} > 5", "domain1", "${var(rand)} < 4", "domain2", "domain3")};
open("http://www.${var(domain)}.com")

*Currently does not work in Chrome Monitors

${InitialTriggerTimestamp}

Syntax: "incident_key": "${initialTriggerTimestamp}"
Purpose: To link reminder and improved alerts to the original trigger alert.
Explanation: When feeding Catchpoint alerts to PagerDuty via API, this command is used to link related alerts and prevent duplication for related alerts.
For more information, see the PagerDuty Integration Guide

${LocationName}

Syntax: ${LocationName}
Purpose: Returns the name of node used to run the test.
Explanation: Used to get the name of node used to run the test.This can be very usesful where a value has to be selected based on the name of node.
Example: Choose a search string based on node location.

// Step - 1
storeVariable("pen", "New York - Level3")
storeVariable("book", "Los Angeles - Level3")
open("http://www.google.com")
typeKeys("//*[@name='q']", ${extractvariable('${locationname}')})

// Step - 2
clickAndWait(//*[@name="btnG"])

Supported Monitors: emulated, Chrome, Mobile

${Password}

Syntax: ${Password}
Purpose: Used to pass the same authentication password set in the test settings of request header within a transaction.
Explanation: Grabs the password from request authentication; works with all the authentication methods.
Example: ${password}
Supported Monitors: Chrome, Mobile

${SequentialListByLocation}

Syntax: ${SequentialListByLocation(value1 <string> <required>, value2 <string> <required>, ..., valueN <string> <required>)}
Purpose: This is used to select a value from a list of values sequentially on a per node basis.
Explanation: Returns a value from a list of values sequentially on a per-node basis.
Example: ${SequentialListByLocation("red", "blue", "green")}
Use case: Open a Google homepage and input a search value from the list in sequential order using round robin algorithm.

// Step - 1
open("[http://www.google.com"](http://www.google.com%22/))
var srchStr = ${SequentialListByLocation('phone', 'tablet', 'laptop', 'desktop')}
typeKeys("//*[@name='q']", "${var(srchStr)}")
setStepName("1.Homepage")

// Step - 2
clickAndWait(//*[@name="btnG"])
setStepName("2.Search")

${SequentialListByRun}

Syntax: ${SequentialListByRun(value1 <string> <required>, value2 <string> <required>, ..., valueN <string> <required>)}
Purpose: This is used to select a value from a list of values sequentially on a per test-run basis.
Explanation: Returns a value from a list of values sequentially on a per test-run basis.
Example: ${SequentialListByRun("red", "blue", "green")}
Use case: Open a Google homepage and input a search value from the list in sequential order. This does not use round robin algorithm.

// Step - 1
open("[http://www.google.com"](http://www.google.com%22/))
var srchStr = ${SequentialListByRun('phone', 'tablet', 'laptop', 'desktop')}
typeKeys("//*[@name='q']", "${var(srchStr)}")
setStepName("1.Homepage")

// Step - 2
clickAndWait(//*[@name="btnG"])
setStepName("2.Search")

${Switch}

Syntax: ${Switch(key, case1, value1, case2, value2..N)}
Purpose: To be able to provide different values depending on different cases.
Explanation: This action instructs the agent to provide different values based on possible different cases, so if the key is looking for a location, and if that location is x, then a value could be 1, or for location y, value is 2, and so on. If the number of parameters is odd in the Switch statement, then the last value is the default condition. This means that a value without a case will serve as an else to be a default value for cases that aren't handled.
Example: In this example, we will generate a random number, and depending on that random number, we will go to a different domain.

var rand = ${random(1,5)};
var domain = ${Switch("${var(rand)}", "0", "domain0", "1", " domain1", "2", " domain2", "3", " domain3", "4", " domain4", "5", " domain5")};
open("http://www.${var(domain)}.com")

Note: The switch macro can NOT be used in the xpath locator or for a verb name.

${TimeTrim}

Syntax: ${TimeTrim(format)}
Purpose: To modify and format the date/time. Will also cut off leading 0's (01:00 will be 1:00)
Explanation: This macro uses today's date. It can modify the date using the sub macros sub() to subtract or add() to add time. The number of time units should be prefixed with the date unit. Days are denoted with d, months are denoted with mo, and years are denoted with y. In addition, hours are denoted with h and minutes are denoted with mi.
Example: ${TimeTrim(MM/DD/YYYY,add(d5))}
Supported Monitors: emulated, Chrome, Mobile

${Time}

Purpose: To modify and format the date/time.
Explanation: It returns UTC time stamp for the time at the node where the test ran in YYYYMMDDHHMISSMSC format (17 characters long). This takes up to three parameters.
- If none, then the current UTC time in YYYYMMDDHHMISSMSC will be returned otherwise, the 1st parameter specifies the format.
- The 2nd parameter (optional, defaults to current time) refers to the start-range.
- The 3rd parameter (optional, defaults to the 2nd parameter value) refers to the end-range.

This macro uses today's date. It can modify the date using the submacros sub() to subtract or add() to add time. The number of time units should be prefixed with the date unit. Days are denoted with d, months are denoted with mo, and years are denoted with y. In addition, hours are denoted with h and minutes are denoted with mi.

Examples:
${time} : 20150930165523136 //Current UTC time in YYYYMMDDHHMISSMSC
${time('YYYY/MM/DD')} //Returns date in format YYYY/MM/DD
${time('YYYY/MM/DD', '2', '4')} //Returns a random date between 2 days in advance to 4 days in advance, tn format YYYY/MM/D
${Time(MM/DD/YY,sub(y4))} //Returns the date in MM/DD/YY format by subtracting year by 4
Supported Monitors: emulated, Chrome, Mobile

>>>>Note - ${Time} - This macro is a scheduler macro and it gets executed by the scheduler and not the node. This will not take the time of execution on the node rather it takes the time that is executed on the node.

You can use this script and can check the screenshot and you will see the difference in Time taken by Catchpoint scheduler and time for Javascript.

open("www.google.com")
runScript("document.getElementsByName('q')[0].value = 'Time(s) macro in CP : '+'${Time(SS)}'+', Time(s) in javascript : '+new Date().getSeconds();")

${Username}

Syntax: ${username}
Purpose: Used to pass the same authentication username set in the test settings of request header within a transaction.
Explanation: Grabs the username from request authentication; works with all the authentication methods.
Example: ${username}
Supported Monitors: Chrome, Mobile

${Var}

Syntax: ${Var( name <string> <required>)}
Purpose: This action extracts an already stored variable for use within the transaction test. It can be assigned via the "var" modifier, or the "storeVariable" command
Explanation: Used for extracting variables within transaction tests. The synonym of this macro is ${ExtractVariable()}.
Example: ${Var(foo)}