Synthetics scripted browser reference (monitor versions 0.5.0+)

This document describes scripted browser functions available for Synthetics monitor versions 0.5.x or higher. If you are using older monitor versions, see the monitor version 0.4.0 and lower documentation.

To determine a monitor's version: Go to synthetics.newrelic.com > (select a monitor) > Settings > General. For more on monitor versions and runtime differences, see Runtime environments.

Selenium Webdriver APIs

The New Relic Synthetics scripted browsers provide access to the 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 via the variables $driver and $browser. In particular:

  • $driver provides all the exports from the selenium-webdriver module (for example, ActionSequence, Button, By, WebElement, etc.).
  • $browser is a New Relic Synthetics instance of selenium-webdriver.WebDriver(). It exposes the main basic WebDriver APIs like get() and findElement(), as well as some Synthetics custom APIs.

Top-level functions: Build your script

New Relic Synthetics calls top-level functions directly from your $browser instance. These provide a wide range of functionality that covers many basic scriptable actions.

Function Description

$browser.actions()

Creates a new action sequence using this driver. For a list of available actions, see ActionSequence.

Return value: void

$browser.addHeader(headerKey: string, headerValue: string)

Adds header headerKey with value headerValue to the runtime.

Return value: void

$browser.addHeaders(headers: ?)

Adds a map of headers to the runtime.

Return value: void

$browser.deleteHeader(header: string)

Deletes a specific header from the runtime.

Return value: void

$browser.deleteHeaders(header: [string])

Deletes all headers in the argument from runtime.

Return value: void

$browser.addHostnameToBlacklist(hostname: string)

Adds a hostname to your deny list. Allows using wildcards.

Return value: void

$browser.addHostnamesToBlacklist(hostnameArr: [string])

Adds all hostnames in an array of arguments to your deny list. Allows using wildcards.

Return value: void

$browser.addHostnameToWhitelist(hostname: string)

Adds a hostname blocked by default in Synthetics to your allow list.

Return value: void

$browser.addHostnamesToWhitelist(hostnameArr: [string])

Adds all hostnames in the argument to your allow list.

Return value: void

$browser.deleteHostnameFromBlacklist(hostname: string)

Removes a hostname for this browser instance from your deny list.

Return value: void

$browser.deleteHostnamesFromBlacklist(hostnameArr: [string])

Removes all hostnames in the argument from your deny list.

Return value: void

$browser.deleteHostnameFromWhitelist(hostnameArr: [string])

Removes a hostname for this browser instance from your allow list.

Return value: void

$browser.deleteHostnamesFromWhitelist(hostnameArr: [string])

Removes all hostnames in the argument from your allow list for this browser instance.

Return value: void

$browser.executeAsyncScript(script: ?, var_args: ?)

Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.

Return value: promise

$browser.executeScript(script: ?, var_args: ?)

Schedules a command to execute JavaScript in the context of the currently selected frame or window.

Return value: promise

$browser.findElement(locator: $driver.Locator)

Schedule a command to find an element on the page. If not found, Synthetics will return an error.

Return value: WebElement

$browser.findElements(locator: $driver.Locator)

Schedule a command to search for multiple elements on the page.

Return value: promise

$browser.waitForAndFindElement(locator: $driver.Locator [, timeout: number)

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, Synthetics will return 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: promise

$browser.get(url: string)

Loads a webpage in a Synthetics browser.

Return value: promise

$browser.getAllWindowHandles()

Schedules a command to retrieve the current list of available window handles.

Return value: promise

$browser.getCapabilities()

A promise that will resolve with the instance's capabilities.

Return value: promise

$browser.getCurrentUrl()

Schedules a command to retrieve the URL of the current page.

Return value: promise

$browser.getHeaders()

Returns a map of currently configured headers.

Return value: map

$browser.getPageSource()

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

$browser.getSession()

A promise for this client's session.

Return value: promise

$browser.getTitle()

Schedules a command to retrieve the current page's title.

Return value: promise

$browser.getWindowHandle()

Schedules a command to retrieve the current window handle.

Return value: promise

$browser.manage()

The options interface for this instance. You can manage cookies, timeouts, and other window options.

Return value: void

$browser.navigate()

The navigation interface (history of browser functions) for this instance.

Return value: void

$browser.schedule(command: ?, description: string)

Schedules a command to be executed by this driver's CommandExecutor.

Return value: promise

$browser.sleep()

Schedules a command to make the driver sleep for the given amount of time.

Return value: promise

$browser.switchTo()

The target locator interface for this instance.

Return value: void

$browser.takeScreenshot()

Schedules a command to take a screenshot.

Return value: promise

$browser.wait(fn: $driver.Condition, timeout: number, opt_message: string)

Schedules a command to wait for a condition to hold, as defined by your supplied function.

Return value: WebElement

$browser.waitForPendingRequests(timeout: number)

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

$browser.addHostnameToBlacklist('*.com');

a.com
$browser.addHostnameToBlacklist('*.*.com'); a.b.com
$browser.addHostnameToBlacklist('*.*.*.com'); a.b.c.com
$browser.addHostnameToBlacklist('www.*.com'); www.a.com
$browser.addHostnameToBlacklist('www.*.*.com'); www.a.b.com
$browser.addHostnameToBlacklist('www.*.*.*.com'); www.a.b.c.com

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

$browser.manage().addCookie(spec: object)

Schedules a command to add a cookie.

spec is a record object describing a browser cookie. For more information, see the Selenium documentation.

Return value: promise

$browser.manage().deleteAllCookies()

Schedules a command to delete all cookies visible to the current page.

Return value: promise

$browser.manage().deleteCookie(name: string)

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

$browser.manage().getCookie(name: string)

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

$browser.manage().getCookies()

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

$browser.manage().timeouts().implicitlyWait(ms: number)

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 0 disables implicit waiting.

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

$browser.manage().timeouts().pageLoadTimeout(ms: number)

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

$browser.manage().timeouts().setScriptTimeout(ms: number)

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

$browser.manage().window().getPosition()

Retrieves the window's current position, relative to the top left corner of the screen.

Return value: promise

$browser.manage().window().getSize()

Retrieves the window's current size.

Return value: promise

$browser.manage().window().maximize()

Maximizes the current window.

Return value: promise

$browser.manage().window().setPosition(x: number, y: number)

Repositions the current window.

Return value: promise

$browser.manage().window().setSize(width: number, height: number)

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

$driver.By.className(className: string)

Locates an element that has a specific class name. The returned locator is equivalent to searching for elements with the CSS selector .clazz.

Return value: locator

$driver.By.css(cssName: string)

Locates an element using a CSS selector.

Return value: locator

$driver.By.id(id: string)

Locates an element by its ID.

Return value: locator

$driver.By.linkText(linkText: string)

Locates link elements whose visible text matches the given string.

Return value: locator

$driver.By.js(js: string)

Locates an element by evaluating a JavaScript expression.

Return value: locator

$driver.By.name(name: string)

Locates elements whose name attribute has the given value.

Return value: locator

$driver.By.partialLinkText(partialLinkText: string)

Locates link elements whose getText visible contains the given substring.

Return value: locator

$driver.By.tagName(tagName: string)

Locates elements with a given tag name. The returned locator is equivalent to using the getElementsByTagName DOM function.

Return value: locator

$driver.By.xpath(xpath: string)

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

click()

Clicks on this element.

Return value: self reference

sendKeys(var_args: ?)

Schedules a command to type a sequence on the DOM element represented by this instance.

Return value: WebElement

getTagName()

Schedules a command to query for the tag/node name of this element.

Return value: WebElement

getCssValue(name: string)

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, #00ff00 instead of rgb(0, 255, 0)).

Return value: promise

getAttribute(name: string)

Schedules a command to query for the value of the given attribute of the element.

Return value: promise

getText(name: string)

Get the visible (not hidden by CSS) innerText of this element, including sub-elements, without any leading or trailing white space.

Return value: promise

getSize()

Schedules a command to compute the size of this element's bounding box, in pixels.

Return value: promise

getLocation()

Schedules a command to compute the location of this element, in page space.

Return value: promise

isEnabled()

Schedules a command to query whether the DOM element represented by this instance is enabled, as dictated by the disabled attribute.

Return value: promise

isSelected()

Schedules a command to query whether this element is selected.

Return value: promise

submit()

Schedules a command to submit the form containing this element (or this element if it is a FORM element). This command is a no-op if the element is not contained in a form.

Return value: promise

clear()

Schedules a command to clear the value of this element.

Return value: promise

isDisplayed()

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

click(opt_elementOrButton: ?, opt_button: ?)

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 WebElement.click().

Return value: actionsequence

doubleClick(opt_elementOrButton: ?, opt_button: ?)

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

dragAndDrop(element: ?, location: ?)

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 x and y: {x: x_offset, y: y_offset}.

Return value: actionsequence

keyDown(key: ?)

Performs a modifier key press. Must be one of ALT, CONTROL, SHIFT, COMMAND, or META. The modifier key is not released until keyUp() or sendKeys() is called. The key press will be targeted at the currently focused element.

Return value: actionsequence

keyUp(key: ?)

Performs a modifier key release. The release is targeted at the currently focused element.

Return value: actionsequence

mouseDown(opt_elementOrButton: ?, opt_button: ?)

Presses a mouse button. The mouse button will not be released until mouseUp is called, regardless of whether that call is made in this sequence or another. The behavior for out-of-order events (such as calling mouseDown() or click() when the button is already held down) is undefined.

Return value: actionsequence

mouseUp(opt_elementOrButton: ?, opt_button: ?)

Releases a mouse button. Behavior is undefined for calling this function without a previous call to mouseDown().

Return value: actionsequence

mouseMove(location: ?, offset: ?)

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

perform()

Executes this action sequence.

Return value: promise

sendKeys(args: ?)

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. New Relic Synthetics 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

isPending()

Whether this promise's value is still being computed.

Return value: boolean

then(opt_callback: fn(T: ?), opt_errback: fn())

Registers listeners for when this instance is resolved. This is the basic function used to link synchronous actions in your script.

Return value: promise

finally(callback: fn())

Registers a listener to invoke when this promise is resolved, regardless of whether the promise's value was successfully computed.

Return value: promise

catch(callback: fn())

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

Conditions: Pause and wait for conditions

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

ableToSwitchToFrame(frame: ?)

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:

  • A numeric index into window.frames for the current frame
  • A webdriver.WebElement, which must reference a FRAME or IFRAME element on the current page
  • A locator which may be used to first locate a FRAME or IFRAME on the current page before attempting to switch to it

Upon successful resolution of this condition, the driver will be left focused on the new frame.

Return value: condition

alertIsPresent()

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

elementIsDisabled(element: $driver.WebElement)

Creates a condition that will wait for the given element to be disabled.

Return value: condition

elementIsEnabled(element: $driver.WebElement)

Creates a condition that will wait for the given element to be enabled.

Return value: condition

elementIsNotVisible(element: $driver.WebElement)

Creates a condition that will wait for the given element to be in the DOM, yet not visible to the user.

Return value: condition

elementIsVisible(element: $driver.WebElement)

Creates a condition that will wait for the given element to become visible.

Return value: condition

elementIsSelected(element: $driver.WebElement)

Creates a condition that will wait for the given element to be selected.

Return value: condition

elementLocated(element: $driver.Locator)

Creates a condition that will loop until an element is found with the given locator.

Return value: condition

elementsLocated(element: $driver.Locator)

Creates a condition that will loop until at least one element is found with the given locator.

Return value: condition

n

elementTextContains(element: $driver.WebElement, substr: string)

Creates a condition that will wait for the given element's visible text to contain the given substring.

Return value: condition

elementTextIs(element: $driver.WebElement, text: string)

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

elementTextMatches(element: $driver.WebElement, regex: string)

Creates a condition that will wait for the given element's visible text to match a regular expression.

Return value: condition

stalenessOf(element: $driver.WebElement)

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

titleContains(substr: string)

Creates a condition that will wait for the current page's title to contain the given substring.

Return value: condition

titleIs(title: string)

Creates a condition that will wait for the current page's title to match the given value.

Return value: condition

titleMatches(regex: string)

Creates a condition that will wait for the current page's title to match the given regular expression.

Return value: condition

For more help

Additional documentation resources include:

Recommendations for learning more: