This document describes scripted browser functions available for synthetic monitors versions 0.5.0 or 0.6.0. If you are using a newer monitor version, see the monitor version Chrome 100 and newer documentation. If you are using older monitor versions, see the monitor version 0.4.0 and lower documentation.
For more on monitor versions and runtime differences, see Runtime environments.
Importante
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.
The Chrome 100+ browser runtime provides backward compatible support for 0.5.0 and 0.6.0 browser runtime syntax.
For some common usage examples, see Introduction to scripted browser monitors.
Selenium Webdriver APIs
By using the variables $driver and $browser, your scripted browsers get access to Selenium Webdriver APIs 3.6.0 for monitor version 0.6.x and Selenium Webdriver APIs 3.5.0 for monitor version 0.5.x.
In particular:
$driverprovides all the exports from theselenium-webdrivermodule (for example,ActionSequence,Button,By,WebElement, etc.).$browseris a synthetic monitoring instance ofselenium-webdriver.WebDriver(). It exposes the main basicWebDriverAPIs likeget()andfindElement(), as well as some synthetic custom APIs.
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 | Description |
|---|---|
| Creates a new action sequence using this driver. For a list of available actions, see ActionSequence. Return value: void |
| Adds header Return value: void |
| Adds a map of headers to the runtime. Return value: void |
| Deletes a specific header from the runtime. Return value: void |
| Deletes all headers in the argument from runtime. Return value: void |
| Adds a hostname to your deny list. Allows using wildcards. Return value: void |
| Adds all hostnames in an array of arguments to your deny list. Allows using wildcards. Return value: void |
| Adds a hostname blocked by default in synthetic monitoring to your allow list. Return value: void |
| Adds all hostnames in the argument to your allow list. Return value: void |
| Removes a hostname for this browser instance from your deny list. Return value: void |
| Removes all hostnames in the argument from your deny list. Return value: void |
| Removes a hostname for this browser instance from your allow list. Return value: void |
| Removes all hostnames in the argument from your allow list for this browser instance. Return value: void |
| Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window. Return value: promise |
| Schedules a command to execute JavaScript in the context of the currently selected frame or window. Return value: promise |
| Schedule a command to find an element on the page. If not found, synthetic monitoring returns an error. Return value: WebElementPromise |
| Schedule a command to search for multiple elements on the page. Return value: 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, synthetic monitoring returns an error. The timeout value is optional. It is 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). Return value: WebElementPromise |
| Loads a webpage in a synthetic browser. Return value: promise |
| Schedules a command to retrieve the current list of available window handles. Return value: promise |
| A promise that will resolve with the instance's capabilities. Return value: promise |
| Schedules a command to retrieve the URL of the current page. Return value: promise |
| Returns a map of currently configured headers. Return value: 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. Return value: promise |
| A promise for this client's session. Return value: promise |
| Schedules a command to retrieve the current page's title. Return value: promise |
| Schedules a command to retrieve the current window handle. Return value: promise |
| The options interface for this instance. You can manage cookies, timeouts, and other window options. Return value: void |
| The navigation interface (history of browser functions) for this instance. Return value: void |
| Schedules a command to be executed by this driver's Return value: promise |
| Schedules a command to make the driver sleep for the given amount of time. Return value: promise |
| The target locator interface for this instance. Return value: void |
| Schedules a command to take a screenshot. Return value: promise |
| Schedules a command to wait for a condition to hold, as defined by your supplied function. Return value: WebElement |
| Causes the script to wait for requests that have been initiated to return, up to the timeout. Useful for tracking non-blocking resources. Return value: promise |
Deny list: Wildcard use
If you want to add domains to the deny list for your browser instance, the wildcards must match the URL syntax of the URL to be blocked.
An overall .com deny list must 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 | Description |
|---|---|
| Schedules a command to add a cookie.
Return value: promise |
| Schedules a command to delete all cookies visible to the current page. Return value: 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. Return value: 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. Return value: 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. Return value: 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. Return value: 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. Return value: 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. Return value: promise |
| Retrieves the window's current position, relative to the top left corner of the screen. Return value: promise |
| Retrieves the window's current size. Return value: promise |
| Maximizes the current window. Return value: promise |
| Repositions the current window. Return value: promise |
| Resizes the current window. Return value: 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. Call them through $driver.By.
Function | Description |
|---|---|
| Locates an element that has a specific class name. The returned locator is equivalent to searching for elements with the CSS selector Return value: locator |
| Locates an element using a CSS selector. Return value: locator |
| Locates an element by its ID. Return value: locator |
| Locates link elements whose visible text matches the given string. Return value: locator |
| Locates an element by evaluating a JavaScript expression. Return value: locator |
| Locates elements whose name attribute has the given value. Return value: locator |
| Locates link elements whose getText visible contains the given substring. Return value: locator |
| Locates elements with a given tag name. The returned locator is equivalent to using the Return value: locator |
| Locates elements matching a XPath selector. Return value: 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. For example, you can click on buttons, sent text to form inputs, and get attributes of elements to test.
Function | Description |
|---|---|
| Clicks on this element. Return value: self reference |
| Schedules a command to type a sequence on the DOM element represented by this instance. Return value: WebElement |
| Schedules a command to query for the tag/node name of this element. Return value: 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, Return value: promise |
| Schedules a command to query for the value of the given attribute of the element. Return value: promise |
| Get the visible (not hidden by CSS) Return value: promise |
| Schedules a command to compute the size of this element's bounding box, in pixels. Return value: promise |
| Schedules a command to compute the location of this element, in page space. Return value: promise |
| Schedules a command to query whether the DOM element represented by this instance is enabled, as dictated by the disabled attribute. Return value: promise |
| Schedules a command to query whether this element is selected. Return value: promise |
| Schedules a command to submit the form containing this element (or this element if it is a Return value: promise |
| Schedules a command to clear the value of this element. Return value: promise |
| Schedules a command to test whether this element is currently displayed. Return value: 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 ActionSequence documentation on GitHub.
Function | Description |
|---|---|
| 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 Return value: actionsequence |
| Double-clicks a mouse button. If an element is provided, the mouse will first be moved to the center of that element. Return value: 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 Return value: actionsequence |
| Performs a modifier key press. Must be one of Return value: actionsequence |
| Performs a modifier key release. The release is targeted at the currently focused element. Return value: actionsequence |
| Presses a mouse button. The mouse button will not be released until Return value: actionsequence |
| Releases a mouse button. Behavior is undefined for calling this function without a previous call to Return value: 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). Return value: actionsequence |
| Executes this action sequence. Return value: 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 on GitHub. Return value: 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, finally() and catch(). For more information, see Sequence actions.
Function | Description |
|---|---|
| Whether this promise's value is still being computed. Return value: boolean |
| Registers listeners for when this instance is resolved. This is the basic function used to link synchronous actions in your script. Return value: promise |
| Registers a listener to invoke when this promise is resolved, regardless of whether the promise's value was successfully computed. Return value: promise |
| Registers a listener for when this promise is rejected. Return value: 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 | Description |
|---|---|
| Move back by one step in the browser's history. Return value: void |
| Move forward by one step in the browser's history. Return value: void |
| Refresh the current page. Return value: void |
| Load a new webpage in the current browser window. Return value: void |
Conditions: Pause and wait for conditions
Dica
You can learn more about waits in Selenium here.
Used with $browser.wait, until pauses your script execution until the condition is matched. For more information, see Selenium's WebDriver until documentation.
The following are available functions for $driver.until.Condition:
Function | Description |
|---|---|
| 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:
|
| 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. Return value: condition |
| Creates a condition that will wait for the given element to be disabled. Return value: condition |
| Creates a condition that will wait for the given element to be enabled. Return value: condition |
| Creates a condition that will wait for the given element to be in the DOM, yet not visible to the user. Return value: condition |
| Creates a condition that will wait for the given element to become visible. Return value: condition |
| Creates a condition that will wait for the given element to be selected. Return value: condition |
| Creates a condition that will loop until an element is found with the given locator. Return value: condition |
| Creates a condition that will loop until at least one element is found with the given locator. Return value: condition n |
| Creates a condition that will wait for the given element's visible text to contain the given substring. Return value: condition |
| Case sensitive. Creates a condition that will wait for the given element's visible text to match the given text exactly. Return value: condition n |
| Creates a condition that will wait for the given element's visible text to match a regular expression. Return value: 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. Return value: condition |
| Creates a condition that will wait for the current page's title to contain the given substring. Return value: condition |
| Creates a condition that will wait for the current page's title to match the given value. Return value: condition |
| Creates a condition that will wait for the current page's title to match the given regular expression. Return value: condition |