You can use synthetic monitoring's scripted browsers to emulate and monitor a custom user experience by scripting browsers that navigate your website, take specific actions, and ensure specific elements are present. For a list of all available functions, see Scripted browser reference.
Scripted monitors are driven by Selenium WebDriverJS. Each time your script runs, New Relic creates a fully virtualized Selenium-driven Google Chrome browser that navigates your website and follows each step of the script. Synthetic monitoring includes an IDE-style script editor what suggests functions, locators, and other elements to simplify scripting.
For a look at how to use the Selenium IDE to record your workflows and export them in the format required by New Relic, watch this short YouTube video (3:49 minutes).
Visit a URL
All scripts begin by specifying which URL the monitor should navigate to. To specify a URL, call $browser.get("url"):
$browser.get("https://mywebsite.com");
Sequence actions
Because WebDriverJS is asynchronous, scripting actions can sometimes execute out of order. To force script actions to execute in order, wrap each action in a then(function(){}) call:
Once you have specified a URL to monitor, you will usually want to locate a particular element on the page. Locating an element verifies its presence on the page, and also allows you to interact with page elements.
You can locate elements by their class, id, link text, name or even XPath. To find these attributes, use your browser's developer tools or view your website's source code. For a list of all locator functions, see Locators: Find page elements.
Locate an element by its HTML class (for example, class="button"). A class is usually specified for CSS styling. When locating an element by class, the monitor will select the first element on the page that has that class:
Locate an element by its exact HTML id (for example, id="edit-submit"). This is a straightforward way to locate page elements, but be careful to specify an id that is not likely to change.
Locate an element by its displayed link text; for example, <a href="http://example.com>your link text here</a>. You can locate by the exact link text ($driver.By.linkText) or by partial match ($driver.By.partialLinkText):
XPath selectors can break when your website's structure changes. For tips on building good XPath selectors, see Optimizing XPath selectors. For an example of locating an element by its xpath, see Search a website.
Tip
To quickly find the XPath for a particular element, use your browser's developer tools. For example, in Chrome:
In Chrome, navigate to the target website.
Right-click the target element, then select Inspect element.
From the Developer Tools panel that opens automatically, look for the highlighted target element.
Right-click the target element, then select Copy XPath.
Interact with elements
Because a scripted monitor drives a real, Selenium-powered Google Chrome browser, scripted monitors can interact with page elements in the same way a user would. For example, the monitor can click a link, enter text in a search box, etc. For a list of available actions, see ActionSequence: Link multiple actions.
For an example of entering text in a field, see Search a website.
Tip
You can add modifier keys (such as ALT and SHIFT) with the keyDown() and keyUp() functions.
Waiting and timeouts
Large page elements, such as images or complex dynamic content, can take a long time to load. This can cause your script to fail when the monitor attempts to interact with or locate an element that hasn't been loaded yet.
After a maximum run time of three minutes, New Relic manually stops the script.
Instruct the monitor to wait for the page title to match a certain value. This ensures that the browser has at least received some data from the target page. To wait for page title, specify an expected title and a timeout value in milliseconds:
//Call the wait function
$browser.wait(function() {
//Tell the monitor to get the page title, then run a function on that title.
return $browser.getTitle().then(function(title) {
//Specify the expected page title.
return title === "Your Page Title Here";
});
//If the condition is not satisfied within a timeout of 1000 milliseconds (1 second), proceed anyway.
Instruct the monitor to wait for a page element to be present. This is useful when an element your script depends on takes a long time to load, or simply to ensure that a page element is present before your script clicks on it.
Use any of the locate functions with the wait function below. Use your desired function instead of the $driver.By.linkText function used below:
//Tell the monitor to wait up to 7,500 milliseconds (7.5 seconds) for a link whose text is `Your Link Text Here`.
$browser.waitForAndFindElement($driver.By.linkText("Your Link Text Here"), 7500);
waitForAndFindElement() will fail to find an element if it's entirely behind another element or if it has a size of 0. It will still find elements with 0 opacity.
Log script results
You can also manually log monitor results to the script log. Use logging to troubleshoot a script: to discover which step of your script is failing, include a log function along with each key step in your script.
Important
The maximum log length is 50,000 bytes. Script logs larger than 50,000 bytes are truncated.
Synthetics blocks popular analytics services' scripts from running by default. You can allow scripts to run for a specified service(s). This allows the service's scripts to run and collect data like it would for a real user.
//Allow Google Analytics scripts to run
$browser.addHostnameToWhitelist(hostnameArr: ['google-analytics.com']);
//Visit https://my-website.com
$browser.get('https://my-website.com');
Customize the user agent
You can customize the scripted browser's user agent to ensure any browser-specific fixes in your app are working properly, or to bypass a security mechanism in order to filter an internal site.
This only spoofs the user-agent HTTP header for the request to the server. It does not change the value of navigator.userAgent.
Import optional modules
You can also import many popular Node.js modules to enhance your test suite, automate the insertion of test data, and simplify complex functions. For more information, see Importing Node.js modules.