This document is for synthetic monitor versions 0.4.x or lower. See also the documentation for Synthetic monitor versions 0.5 or 0.6.0 and monitor version Chrome 100 and newer.
Important
As of August 26, 2024, you can no longer create new monitors using legacy runtimes on public or private locations.
On October 22, 2024, we will end of life the containerized private minion (CPM) and legacy synthetics runtime versions. For public locations, use the runtime upgrade UI to update your monitors to the newest runtimes. For private locations, please review our recommended migration steps to avoid monitor degradation.
For some common usage examples, see Introduction to scripted browser monitors.
Overview
Synthetic scripted browsers provide you access to the Selenium Webdriver APIs 2.47.0 via the variables $driver
and $browser
. In particular:
$driver
provides all the exports from theselenium-webdriver
module (for example,ActionSequence
,Button
,By
,WebElement
, etc.).$browser
is a synthetic-flavored instance ofselenium-webdriver.WebDriver()
: it exposes the main basicWebDriver
APIs likeget()
andfindElement()
, as well as some synthetic custom APIs.
This document describes the functions available for synthetic scripted browser monitors version 0.4.0 or lower. For the newest monitor documentation, see monitor version 0.5.0+ documentation.
Other relevant documentation:
- For more on synthetic scripting, see Write scripted browsers.
- For example scripts, see Scripted browser examples.
- For more information about monitor versions and runtime differences, see Runtime environments.
- To view and share scripted browser examples, check out topics tagged synthetic-script in New Relic's Support Forum.
Top-level functions: Build your script
New Relic calls top-level functions directly from your $browser
instance. These provide a wide range of functionality that covers many basic scriptable actions.
Function | Return value |
---|---|
Creates a new action sequence using this driver. For a list of available actions, see ActionSequence: Link multiple actions. | void |
Adds header | void |
Adds a map of headers to the runtime. | void |
Deletes a specific header from the runtime. | void |
Deletes all headers in argument from runtime. | void |
Disallows a hostname. Allows use wildcards. | void |
Disallows all hostnames in an array of arguments. Allows use wildcards. | void |
Allows a hostname blocked by default in synthetic monitoring. | void |
Allows all hostnames in argument. | void |
Removes a hostname from this browser instance's blacklist. | void |
Removes all hostnames in argument from the disallowed list. | void |
Removes a hostname from this browser instance's allowed list. | void |
Removes all hostnames in argument from this browser instance's allowed list. | void |
Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window. | promise |
Schedules a command to execute JavaScript in the context of the currently selected frame or window. | promise |
Schedule a command to find an element on the page. If not found, New Relic returns an error. | WebElement |
Schedule a command to search for multiple elements on the page. | promise |
Schedule a command to wait for and find an element on the page, and another command to wait for it to be visible. If not found, New Relic returns an error. The timeout value is an optional one, and gets applied separately to both tasks of finding the element and waiting for its visibility. This means at worst case, this method can take up to twice the provided timeout value. The default timeout value is 1000 ms (1 second). | promise |
Loads a webpage in a synthetic browser. | promise |
Schedules a command to retrieve the current list of available window handles. | promise |
A promise that will resolve with the instance's capabilities. | promise |
Schedules a command to retrieve the URL of the current page. | promise |
Returns a map of currently configured headers. | map |
Schedules a command to retrieve the current page's source. The page source returned is a representation of the underlying DOM; do not expect it to be formatted or escaped in the same way as the response sent from the web server. | promise |
A promise for this client's session. | promise |
Schedules a command to retrieve the current page's title. | promise |
Schedules a command to retrieve the current window handle. | promise |
Schedules a command to test if an element is present on the page. If given a DOM element, this function will check if it belongs to the document the driver is currently focused on. Otherwise, the function will test if at least one element can be found with the given search criteria. | promise |
The options interface for this instance. You can manage cookies, timeouts, and other window options. | void |
The navigation interface (history of browser functions) for this instance. | void |
Schedules a command to be executed by this driver's CommandExecutor. | promise |
Schedules a command to make the driver sleep for the given amount of time. | promise |
The target locator interface for this instance. | void |
Schedule a command to take a screenshot. | promise |
Schedules a command to wait for a condition to hold, as defined by some user supplied function. | webElement |
Causes the script to wait for requests that have been initiated to return, up to the timeout. Useful for tracking non-blocking resources. | promise |
Disallow list: Wildcard use
Disallowing domains for your browser instance requires wildcards to match the URL syntax of the URL to be blocked.
An overall .com
disallowed list needs to contain these functions:
Function | Blocking action |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Options: Manage the browser instance
These functions manage options for your browser instance such as cookies, timeouts and window size. Access these options through the $browser.manage()
function.
Function | Return value |
---|---|
Schedules a command to add a cookie. | promise |
Schedules a command to delete all cookies visible to the current page. | promise |
Schedules a command to delete the cookie with the given name. This command is a no-op if there is no cookie with the given name visible to the current page. | promise |
Schedules a command to retrieve the cookie with the given name. Returns null if there is no such cookie. The cookie will be returned as a JSON object as described by the WebDriver wire protocol. | promise |
Schedules a command to retrieve all cookies visible to the current page. New Relic Syntheticcs returns each cookie as a JSON object as described by the WebDriver wire protocol. | promise |
Specifies the amount of time the driver should wait when searching for an element if it is not immediately present. Setting the wait timeout to Be careful increasing the wait timeout, as it will increase test run time, especially with slower location strategies like XPath. Default is 10 seconds. | promise |
Sets the amount of time to wait for a page load to complete before returning an error. If the timeout is negative, page loads may last up to 180 seconds. Default is 60 seconds. | promise |
Sets the amount of time to wait, in milliseconds, for an asynchronous script to finish execution before returning an error. Default is 30 seconds. | promise |
Retrieves the window's current position, relative to the top left corner of the screen. | promise |
Retrieves the window's current size. | promise |
Maximizes the current window. | promise |
Repositions the current window. | promise |
Resizes the current window. | promise |
Locators: Find page elements
Locators are a collection of factory functions for creating locator
instances. Locators find DOM elements, which can be passed to functions such as $browser.findElement
or $browser.isElementPresent
. Call them through $driver.By
.
Function | Return value |
---|---|
Locates an element that has a specific class name. The returned locator is equivalent to searching for elements with the CSS selector | locator |
Locates an element using a CSS selector. | locator |
Locates an element by its ID. | locator |
Locates link elements whose visible text matches the given string. | locator |
Locates an element by evaluating a JavaScript expression. | locator |
Locates elements whose name attribute has the given value. | locator |
Locates link elements whose getText visible contains the given substring. | locator |
Locates elements with a given tag name. The returned locator is equivalent to using the | locator |
Locates elements matching a XPath selector. | locator |
WebElement: Interact with page elements
When a function such as $browser.findElement
or $browser.waitForAndFindElement
returns a WebElement reference, these functions can be used to interact with that element. Using these, you can click on buttons, sent text to form inputs, and get attributes of elements to test.
Function | Return value |
---|---|
Clicks on this element. | void |
Schedules a command to type a sequence on the DOM element represented by this instance. | WebElement |
Schedules a command to query for the tag/node name of this element. | WebElement |
Schedules a command to query for the computed style of the element represented by this instance. If the element inherits the named style from its parent, the parent will be queried for its value. Where possible, color values will be converted to their hex representation (for example, | promise |
Schedules a command to query for the value of the given attribute of the element. | promise |
Get the visible (not hidden by CSS) | promise |
Schedules a command to compute the size of this element's bounding box, in pixels. | promise |
Schedules a command to compute the location of this element, in page space. | promise |
Schedules a command to query whether the DOM element represented by this instance is enabled, as dictated by the disabled attribute. | promise |
Schedules a command to query whether this element is selected. | promise |
Schedules a command to submit the form containing this element (or this element if it is a | promise |
Schedules a command to clear the value of this element. | promise |
Schedules a command to test whether this element is currently displayed. | promise |
Schedules a command to retrieve the outer HTML of this element. | promise |
Schedules a command to retrieve the inner HTML of this element. | promise |
ActionSequence: Link multiple actions
Action sequences can create complex user interactions with your website.
- To create a new action sequence, use
$browser.actions()
. - To link multiple actions together into a sequence, include
perform()
after each. This executes and then terminates individual sequences, including single-action sequences.
The following table contains a list of available actions. For more information, see the WebDriver actions documentation.
Function | Return value |
---|---|
Clicks a mouse button. If an element is provided, the mouse will first be moved to the center of that element. This is equivalent to | actionsequence |
Double-clicks a mouse button. If an element is provided, the mouse will first be moved to the center of that element. | actionsequence |
Convenience function for performing a "drag and drop" maneuver. The target element may be moved to the location of another element, or by an offset (in pixels). The location is an object with two properties | actionsequence |
Performs a modifier key press. Must be one of | actionsequence |
Performs a modifier key release. The release is targeted at the currently focused element. | actionsequence |
Presses a mouse button. The mouse button will not be released until | actionsequence |
Releases a mouse button. Behavior is undefined for calling this function without a previous call to | actionsequence |
Moves the mouse. The location to move to may be specified in terms of the mouse's current location, an offset relative to the top-left corner of an element, or an element (in which case the middle of the element is used). | actionsequence |
Executes this action sequence. | promise |
Simulates typing multiple keys. Each modifier key encountered in the sequence will not be released until it is encountered again. All key events will be targeted at the currently focused element. For a full list of supported non-alphanumeric keys, see the WebDriver enum key documentation. | actionsequence |
Promises: Link actions into sequences
You can also execute functions directly on promises. Synthetic monitoring is a native Node.js environment and uses standard Node.js promises.
These functions evaluate the status of promises, cancel them, and more. In particular, you can create sequences of actions with the then()
function and its siblings, thenFinally()
and thenCatch()
. For more information, see Sequence actions.
Function | Return value |
---|---|
Cancels the computation of this promise's value, rejecting the promise in the process. This method is a no-op if the promise has already been resolved. | void |
Whether this promise's value is still being computed. | boolean |
Registers listeners for when this instance is resolved. This is the basic function used to link synchronous actions in your script. | promise |
Registers a listener to invoke when this promise is resolved, regardless of whether the promise's value was successfully computed. | promise |
Registers a listener for when this promise is rejected. | promise |
Navigate: Move through browser history
The $browser.navigate()
function exposes a number of functions that allow you to move backwards and forwards through your browser history, refresh your page and navigate to new pages.
Function | Return value |
---|---|
Move back by one step in the browser's history. | void |
Move forward by one step in the browser's history. | void |
Refresh the current page. | void |
Load a new webpage in the current browser window. | void |
Conditions: Pause and wait for conditions
Used with $browser.wait
, until
pauses your script execution until the condition is matched. For more information on explicit and implicit waits, see the WebDriver documentation.
For .wait
and .until
usage examples, see Webdriver.wait examples.
The following are available functions for $driver.until.Condition
:
Function | Return value |
---|---|
Creates a condition that will wait until the input driver is able to switch to the designated frame. The target frame may be specified as:
| condition |
Creates a condition that waits for an alert to be opened. Upon success, the returned promise will be fulfilled with the handle for the opened alert. | condition |
Creates a condition that will wait for the given element to be disabled. | condition |
Creates a condition that will wait for the given element to be enabled. | condition |
Creates a condition that will wait for the given element to be in the DOM, yet not visible to the user. | condition |
Creates a condition that will wait for the given element to become visible. | condition |
Creates a condition that will wait for the given element to be selected. | condition |
Creates a condition that will loop until an element is found with the given locator. | condition |
Creates a condition that will loop until at least one element is found with the given locator. | condition |
Creates a condition that will wait for the given element's visible text to contain the given substring. | condition |
Case sensitive. Creates a condition that will wait for the given element's visible text to match the given text exactly. | condition |
Creates a condition that will wait for the given element's visible text to match a regular expression. | condition |
Creates a condition that will wait for the given element to become stale. An element is considered stale once it is removed from the DOM, or a new page has loaded. | condition |
Creates a condition that will wait for the current page's title to contain the given substring. | condition |
Creates a condition that will wait for the current page's title to match the given value. | condition |
Creates a condition that will wait for the current page's title to match the given regular expression. | condition |