Synthetics scripted browser reference (monitor versions 0.4.x or lower)

This document is for Synthetics monitor versions 0.4.x or lower. See also the documentation for Synthetics monitor versions 0.5 or higher.

To determine a monitor's version: Go to synthetics.newrelic.com > (select a monitor) > Settings > General.

New Relic Synthetics 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 the selenium-webdriver module (for example, ActionSequence, Button, By, WebElement, etc.).
  • $browser is a New Relic Synthetics-flavored instance of selenium-webdriver.WebDriver(): it exposes the main basic WebDriver APIs like get() and findElement(), as well as some Synthetics custom APIs.

This document describes the functions available for Synthetics scripted browser monitors version 0.4.0 or lower. For the newest monitor documentation, see monitor version 0.5.0+ documentation.

Other relevant documentation:

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 Return value

$browser.actions()

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

void

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

Adds header headerKey with value headerValue to the runtime.

void

$browser.addHeaders(headers: ?)

Adds a map of headers to the runtime.

void

$browser.deleteHeader(header: string)

Deletes a specific header from the runtime.

void

$browser.deleteHeaders(header: [string])

Deletes all headers in argument from runtime.

void

$browser.addHostnameToBlacklist(hostname: string)

Blacklists a hostname. Allows use wildcards.

void

$browser.addHostnamesToBlacklist(hostnameArr: [string])

Blacklists all hostnames in an array of arguments. Allows use wildcards.

void

$browser.addHostnameToWhitelist(hostname: string)

Whitelists a hostname blocked by default in Synthetics.

void

$browser.addHostnamesToWhitelist(hostnameArr: [string])

Whitelists all hostnames in argument.

void

$browser.deleteHostnameFromBlacklist(hostname: string)

Removes a hostname from this browser instance's blacklist.

void

$browser.deleteHostnamesFromBlacklist(hostnameArr: [string])

Removes all hostnames in argument from blacklist.

void

$browser.deleteHostnameFromWhitelist(hostnameArr: [string])

Removes a hostname from this browser instance's whitelist.

void

$browser.deleteHostnamesFromWhitelist(hostnameArr: [string])

Removes all hostnames in argument from this browser instance's whitelist.

void

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

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

promise

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

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

promise

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

Schedule a command to find an element on the page. If not found, New Relic Synthetics returns an error.

WebElement

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

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

promise

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

Schedule a command to find an element on the page. If not found, New Relic Synthetics returns an error. The timeout value is an optional one. The default timeout value is 1000 ms (1 second).

promise

$browser.get(url: string)

Loads a webpage in a New Relic Synthetics browser.

promise

$browser.getAllWindowHandles()

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

promise

$browser.getCapabilities()

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

promise

$browser.getCurrentUrl()

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

promise

$browser.getHeaders()

Returns a map of currently configured headers.

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.

promise

$browser.getSession()

A promise for this client's session.

promise

$browser.getTitle()

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

promise

$browser.getWindowHandle()

Schedules a command to retrieve the current window handle.

promise

$browser.isElementPresent(locatorOrElement: $driver.Locator)

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

$browser.manage()

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

void

$browser.navigate()

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

void

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

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

promise

$browser.sleep()

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

promise

$browser.switchTo()

The target locator interface for this instance.

void

$browser.takeScreenshot()

Schedule a command to take a screenshot.

promise

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

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

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.

promise

Blacklist: Wildcard use

Blacklisting domains for your browser instance requires wildcards to match the URL syntax of the URL to be blocked.

An overall .com blacklist needs to 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 Return value

$browser.manage().addCookie(name: string, value: string, opt_path: string, opt_domain: string, opt_isSecure: boolean, opt_expiry: number)

Schedules a command to add a cookie.

promise

$browser.manage().deleteAllCookies()

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

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.

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.

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.

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.

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.

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.

promise

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

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

promise

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

Retrieves the window's current size.

promise

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

Maximizes the current window.

promise

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

Repositions the current window.

promise

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

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

$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.

locator

$driver.By.css(cssName: string)

Locates an element using a CSS selector.

locator

$driver.By.id(id: string)

Locates an element by its ID.

locator

$driver.By.linkText(linkText: string)

Locates link elements whose visible text matches the given string.

locator

$driver.By.js(js: string)

Locates an element by evaluating a JavaScript expression.

locator

$driver.By.name(name: string)

Locates elements whose name attribute has the given value.

locator

$driver.By.partialLinkText(partialLinkText: string)

Locates link elements whose getText visible contains the given substring.

locator

$driver.By.tagName(tagName: string)

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

locator

$driver.By.xpath(xpath: string)

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

click()

Clicks on this element.

void

sendKeys(var_args: ?)

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

WebElement

getTagName()

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

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)).

promise

getAttribute(name: string)

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

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.

promise

getSize()

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

promise

getLocation()

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

promise

isEnabled()

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

promise

isSelected()

Schedules a command to query whether this element is selected.

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.

promise

clear()

Schedules a command to clear the value of this element.

promise

isDisplayed()

Schedules a command to test whether this element is currently displayed.

promise

getOuterHtml()

Schedules a command to retrieve the outer HTML of this element.

promise

getInnerHtml()

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 ActionSequence documentation.

Function Return value

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

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.

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}.

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.

actionsequence

keyUp(key: ?)

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

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.

actionsequence

mouseUp(opt_elementOrButton: ?, opt_button: ?)

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

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).

actionsequence

perform()

Executes this action sequence.

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.

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, thenFinally() and thenCatch(). For more information, see Sequence actions.

Function Return value

cancel(string: reason)

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

isPending()

Whether this promise's value is still being computed.

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.

promise

thenFinally(callback: fn())

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

promise

thenCatch(callback: fn())

Registers a listener for when this promise is rejected.

promise

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

Conditions: Pause and wait for conditions

Used with $browser.wait, until pauses your script execution until the condition is matched. For more information, see the WebDriver until documentation.

The following are available functions for $driver.until.Condition:

Function Return value

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.

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.

condition

elementIsDisabled(element: $driver.WebElement)

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

condition

elementIsEnabled(element: $driver.WebElement)

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

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.

condition

elementIsVisible(element: $driver.WebElement)

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

condition

elementIsSelected(element: $driver.WebElement)

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

condition

elementLocated(element: $driver.Locator)

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

condition

elementsLocated(element: $driver.Locator)

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

condition

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

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

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.

condition

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

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

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.

condition

titleContains(substr: string)

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

condition

titleIs(title: string)

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

condition

titleMatches(regex: string)

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

condition

For more help

Additional documentation resources include:

Recommendations for learning more: