For the complete documentation index, see llms.txt. This page is also available as Markdown.

Getting Started with Transactions

Introduction

ThousandEyes transaction tests are Web layer tests similar to HTTP server tests and page load tests, except that transaction tests can interact with their targets in order to mimic multi-step user journeys or API sequences. Transaction tests provide greater insight into user experience, and enable you to ensure that those user journeys complete successfully.

Compare these three web layer test types below:

The ThousandEyes Cloud or Enterprise Agent sends a single request and expects a single valid response. Measures response time and validates the HTTP status code to compute server availability. HTTP server tests are used to monitor web servers to ensure they are available and performant.

ThousandEyes agent runs Chromium in order to request and render a single web page. Chromium sends an initial request for the page, then renders the response, and iteratively requests all of the components within the page, including images, JavaScript files, CSS, and AJAX requests. Page load tests monitor the web server that serves the page and all of the page's dependencies. A page load test can be thought of as multiple HTTP server tests combined in one.

Browser Synthetics: Agent runs Chromium which is automatically driven by a Selenium script. The script can navigate through multiple pages and interact with them. A browser synthetics transaction test can be thought of as multiple page load tests combined in one.

API Monitoring: Agent runs a script in Node.js to sequentially or iteratively make arbitrary API requests towards the target using the node-fetch library.

When to Use a Transaction Test

Transaction tests measure web user experience using either synthetic browser interactions, or sequences of API requests. Transaction tests should be used for testing multi-step workflows. This type of test can uncover problems that aren't always apparent from loading a single page, as with a page load test, or sending a single request, as with an HTTP server test. For example, if your app or web site relies on returning customer data from somewhere else after the user logs in, you'll need a transaction test to evaluate this part of the user experience past the login screen.

Some examples of transaction tests include:

  • Productivity SaaS: Log in, browse to a shared documents folder, and download a file.

  • Shopping/e-commerce: Load the main page, search for a specific product by name, add it to a shopping cart, and complete the purchase using a dummy credit card.

  • Web conferencing: Log in, schedule a meeting, and join the meeting in the browser with a virtual camera and microphone

Terminology

  • BrowserBot is a component of the ThousandEyes Cloud Agents and Enterprise Agents that manages page load and transaction tests. This is accomplished by running an instance of the Chromium web browser which can be driven automatically via Selenium from Node.js. Complete details are available in the What is BrowserBot? article.

  • Selenium is an open source software library for browser automation. Transaction tests leverage the Selenium API in Node.js for automating the Chromium web browser.

  • node-fetch is an open source software library for making HTTP requests. Transaction tests leverage node-fetch within Node.js for API monitoring, allowing you to script machine-to-machine workflows such as back-end API call sequences.

  • Node.js is a JavaScript runtime environment included in BrowserBot which is used to execute scripts for transaction tests.

  • JavaScript is the programming language in which transaction scripts are written. You do not need to be a JavaScript expert to work with transaction tests, but some JavaScript knowledge will allow you to create more advanced transaction scripts.

Getting Started with Google Chrome Recorder

Google Chrome includes a built-in Recorder panel in DevTools that allows you to record, replay, and measure user flows. You can export these recordings and import them into ThousandEyes as a transaction test script.

Use Google Chrome Recorder to capture the click path and selectors for the user journey. Treat the exported JSON as a starting point. Most script updates, including selector cleanup, waits, credentials, markers, and screenshots, should happen in the ThousandEyes script editor and be validated against the Cloud or Enterprise Agents that will run the scheduled test.

Using Google Chrome Recorder

Before you import a recording, make sure your ThousandEyes role includes the Create web transaction tests permission to create a new transaction test, or the Edit tests permission to update an existing transaction test. To validate the script with an instant test, your role also needs the View agents in account group permission. If you cannot import, save, or run the instant test, see Role-Based Access Control, Explained.

  1. Open Google Chrome and navigate to the page where you want to start your transaction.

  2. Open Chrome DevTools and open the Recorder panel.

  3. Click Start recording and perform the steps of your transaction.

  4. Click End recording when finished.

  5. Export the recording as JSON.

  6. Import the script into ThousandEyes to create or update your transaction test.

  7. Review the imported script in the ThousandEyes script editor before you run the test. Replace any cleartext secrets with credentials, enable those credentials in the transaction test settings, add markers and screenshots, and align Device Emulation or window size settings with the Chrome recording if the flow depends on a specific viewport.

For a video walkthrough of how to use the Google Chrome Recorder import feature, see: Google Chrome Recorder Import Feature Walkthrough

For more information on the Google Chrome Recorder, see the Google Chrome Recorder documentation.

Browser Transaction Development Workflow

Use the following workflow to create and validate a browser transaction test. For API-monitoring transaction tests, see Include API Calls in a Transaction Test.

  1. Record the user journey in Google Chrome Recorder.

  2. Export the recording as JSON.

  3. Import the JSON file into ThousandEyes.

  4. Review and update the generated script in the ThousandEyes script editor. Replace any cleartext secrets with credentials before the first run, enable those credentials in the transaction test settings, and align Device Emulation or window size settings with the Chrome recording if the flow depends on a specific viewport.

  5. Run an instant test on the Cloud or Enterprise Agents configured for the scheduled test.

  6. Add or adjust markers and screenshots as needed, and then validate the test again before relying on it.

Create a Browser Transaction

Use Google Chrome Recorder to capture the click path and selectors for a simple user journey. The exported JSON gives you a starting point for the ThousandEyes transaction script, but the most important iteration happens after you import the script into ThousandEyes and run it against the agents that will run the scheduled test.

For example, record a transaction that starts at https://google.com, enters "ThousandEyes product documentation" in the search field, submits the search, and opens the ThousandEyes product documentation site from the results. After you import the recording into ThousandEyes, the generated script might look similar to the following example:

You have now created a first transaction test script. The next step in the browser synthetics development workflow is to run an instant test to verify it works as expected. If you want a better understanding of the generated code for this transaction script, continue to the next section. Otherwise, jump ahead to Run an Instant Test.

Breaking down the script line by line

The first two lines of the script are import declarations. The transaction script runs in Node.js, a JavaScript runtime environment, and can import code from outside of the script. In this case, the generated script imports code from two packages named "selenium-webdriver" and "thousandeyes".

The first declaration, shown above, imports a class named By and an enumeration named Key from Selenium. The By class is used for specifying the method for locating an element within a webpage. To interact with an element, like clicking or typing into it, Selenium must first be able to locate the element. Elements will be generally located in one of the following ways:

  • className: Locates elements that have a specific class name.

  • css: Locates elements using a CSS selector

  • id: Locates elements by the ID attribute

  • linkText: Locates link elements whose visible text matches the given string

  • name: Locates elements whose name attribute has the given value

  • xpath: Locates elements matching a XPath selector

The Key enumeration provides representations of pressable keys that aren't text, such as the Alt, Shift, Tab, and Enter keys. The generated script imports this enumeration because the recorded flow pressed the Enter key.

The second declaration imports two modules provided by ThousandEyes. The first module, driver , is an instance of Selenium's WebDriver class that has been instantiated to work with the Chromium browser on the agent. See the Controlling the Browser section of the Transaction Scripting Reference for the full list of supported methods. The second module, test, provides an interface to the transaction test configuration, such as getting the target test URL or test interval. See the Getting Test Configuration Settings section of the Transaction Scripting Reference for full documentation and example usage.

The line above calls the runScript function, which contains the interactions that were recorded. The runScript function is defined in the following lines.

This line begins the definition for runScript function.

This line calls the generated configureDriver function. The configureDriver function configures the driver instance's implicit timeout. The implicit timeout specifies the maximum amount of time to wait when attempting to locate elements on the page. Without calling configureDriver, the default value is 0, which is not very forgiving on modern websites and will often throw errors that elements could not be found because the page had not fully loaded. In this example, the generated function sets the value to 7 seconds.

This line calls the getSettings method from the test module and stores the result in a variable named settings.

This line calls the get method of the driver instance to navigate to a specific URL. It references the settings variable from the previous line to use the target URL from the test configuration.

This line is generated from clicking on the search field on the Google search page. It calls a generated helper function named click, with an element selector using By.name, which was imported earlier from Selenium. The value of the name selector, "q", corresponds to the HTML name attribute of the search field on Google’s page.

The typeText helper function types text into a given field. It accepts two parameters: first, the text to type, and second, a selector to locate the element in which to type that text.

The pressEnter helper function presses the Enter key. It accepts one parameter, a selector to locate the element in which to press the Enter key.

The last line in the runScript function is generated from clicking on the ThousandEyes Product Documentation link on the search results page. Here, the script uses a different selector, By.css, to locate the link.

The closing curly brace concludes the definition of the runScript function.

The generated helper functions mentioned above, such as configureDriver, click, typeText, and pressEnter, are defined below the definition of the runScript function.

Run an Instant Test

Once you have imported and reviewed a transaction script, run an actual transaction instant test in ThousandEyes to verify that it works as expected. In the test settings, select the agents that will run the scheduled test, then run the instant test and review the transaction results.

If you need to evaluate the script with the newer Chromium version, run an instant test on a Cloud Agent or on an Enterprise Agent enabled for dual Chromium, and set Browser Options to Newer when available. This validates the script in the same platform workflow used for scheduled transaction tests.

If the instant test succeeds, optimize the script by adding markers, screenshots, and credentials as needed. If the instant test fails, continue to troubleshooting the script so that it correctly and completely emulates the user journey without errors.

Optimize

Once your transaction script successfully runs without any errors, optimize the script with the features described below. After adding your optimizations, run another instant test to verify it still works as expected. You can use AI-assisted development tools to help iterate on selectors, waits, and script structure, but treat their output as draft code and validate every change with an instant test.

Markers

You can use markers to define and measure discrete steps within a user journey or business transaction. For example, an e-commerce checkout transaction might include steps for "Item Search", "Add to Cart", and "Submit Order", and each step might include multiple actions like clicking and typing. Markers are used to delineate such steps and measure the time taken for each. By identifying where a script section starts and stops, you can compare markers across test rounds and against the overall transaction time. If the performance of the whole transaction degrades, markers allow you to quickly see which step(s) in the transaction took longer to complete than they normally would. When an error occurs inside of a marker, the marker will show as "Incomplete" in the test view which can identify the specific phase of the transaction that had an error. Marker times are displayed on the timeline and waterfall in transaction test views and can also be used in alert rules and dashboards.

Diagram displaying Search and Add to Cart transaction steps and the length of time for each step

There are two ways to use markers:

  • the set method creates a marker with the supplied name that spans from transaction start time to the time this method is called

  • the start and stop methods start and stop a marker with the supplied name at the time they are called

To use markers in your script, you must include the markers module in the thousandeyes import line at the top of the script.

Clicking the Add marker button (Visual representation of Add marker button) will:

  • Add markers to the import { ... } from 'thousandeyes' import declaration, if the module is not already imported

  • Add two lines of code for markers.start and markers.stop at the cursor position in the script editor

The markers module is documented in the Transaction Scripting Reference. The code below shows how to add markers to the example script from the Create a Browser Transaction section above.

Screenshots

Screenshots are useful to track progress and ensure the page visually matches what you were intending to see. You can capture a screenshot of the browser’s viewport by adding the following line of code inside your script. No additional import declarations are required because the takeScreenshot method belongs to the driver class that has already been imported.

Up to 12 screenshots captured during a transaction will be included with the test results in the platform, as described in Screenshots in Transaction Test Views. It can still be useful to capture screenshots throughout the workflow because if the script encounters an error before completing, you can inspect the state of the webpage leading up to the error. One screenshot will be automatically captured at the time the error occurs.

Capturing screenshots requires a small-but-non-zero amount of time on the order of one half second. Whenever possible screenshots should not be captured gratuitously and should be captured after stopping one marker and before starting the next.

You can disable screenshots by unchecking the Screenshots > Enabled checkbox in the test's Advanced Settings tab in the ThousandEyes platform. Unchecking this box will prevent screenshots from being captured when driver.takeScreenshot() is called or when an error occurs.

Credentials

In some cases, such as typing in password forms, you should not store the values you typed as cleartext in the transaction script. ThousandEyes provides a credential repository that stores and retrieves sensitive information like passwords, authentication tokens, and two-factor authentication secrets.

If your imported script includes a username, password, or other secret value, create the credential in the ThousandEyes credentials repository, enable it in the transaction test settings, and then replace the cleartext value in the script editor with a credential reference. Use a meaningful credential name so the script remains readable and easier to maintain.

If the imported script does not already import credentials, add it to the ThousandEyes import statement:

For more information, see Working With Secure Credentials.

Troubleshooting

You might find that some imported transaction scripts raise an unexpected error during an instant test or scheduled test on Cloud and Enterprise Agents in the ThousandEyes platform. While many imported flows will result in functional scripts, at times it will be necessary to manually alter the generated output. This section will help you to troubleshoot your transaction scripts to identify the cause of errors and how to fix them.

To most effectively troubleshoot transaction scripts, you should have some familiarity with the browser's web development tools. See the Working With Web Development Tools article for more information and resources.

Useful Functions for Troubleshooting

console.log

You can use console.log statements to help debug, such as printing the current line number, for example console.log("Line 7"), or the value of a variable, for example console.log(settings.url).

driver.sleep

You can use driver.sleep to slow down script execution when debugging or if you want to sit at one step for a long time (for instance, to inspect elements in the page using the web development tools). The driver.sleep function takes a single parameter, the amount of time to sleep in milliseconds. Example usage:

Clicking the Add sleep button Visual representation of Add sleep button will insert code to call driver.sleep at the cursor position in the script editor.

Common Errors

NoSuchElementError

The most common error is NoSuchElementError which indicates that Selenium was unable to locate an element within the page with the given selector. This usually occurs for one of the reasons explained below.

Element did not exist (yet)

Today's web applications commonly use client-side rendering to build their pages. Compared to server-side rendering, which generates the full HTML document and sends it to the client in the initial request, with client-side rendering the server only sends an initial scaffold in the first request and then uses JavaScript to dynamically fetch data and render it in the page. Selenium will begin its attempt to locate an element after the initial page load, but does not necessarily wait for all the JavaScript to finish executing.

If the transaction is failing because it cannot locate an element, you can try increasing the implicit value in the configureDriver function. For example, the code below sets the implicit wait to 15 seconds. Note that the value is in milliseconds, which is why * 1000 is used.

Element did exist, but selector did not match

Some pages contain elements that do not have consistent attributes, which might cause a generated selector to match while recording but not match when the transaction test runs. There are two easy ways to identify if this is the cause of your NoSuchElementError:

  1. Use the console.log and driver.sleep functions immediately before the line of code that raises the NoSuchElementError, then run an instant test again and review the result details. Use screenshots and browser developer tools to inspect the element, comparing its attributes with the selector used in the script. It might be helpful to repeat this more than once.

  2. Record the transaction again with Google Chrome Recorder and compare the selectors between the first and second recordings. Keep a copy of the original script before you import or paste a new version into the script editor.

Element was in a different tab or window

Some browser actions might cause a new browser tab (or window) to open. If the script does not switch to the correct tab, it can look for an element in one page when the element exists in another page in a different tab.

To change the active tab, you can use the driver.switchTo function. Two examples are available in the transaction scripting examples repository:

  1. switchToNextTab.js: Shows how to switch to the next tab, including wrapping around to the first tab from the last tab

  2. switchToTabWithUrl.js: Shows how to switch to a specific tab given its URL

ElementClickInterceptedError

The ElementClickInterceptedError will occur when Selenium attempts to click on an element but it is covered by one or more other elements. This can happen when the web page uses the CSS z-index property to overlay elements on top of other elements. This normally occurs when a popup dialog is shown or when sticky navigation bars or footers scroll with the page.

To avoid this error, be sure to wait for and dismiss any automatic modal popups while recording. If the target element is covered by a sticky navbar or footer, try using the scrollElementIntoView function from the from the transaction scripting examples repository.

ElementNotInteractableError and WebDriverError: element not interactable

These errors will occur when Selenium attempts to interact with an element that is not visible, for example to click or type into it. In contrast to the NoSuchElementError, the element does exist and was successfully located, but Selenium cannot interact with it because it is not rendered in the page.

This commonly occurs when interacting with an element that is only visible while hovering the mouse pointer over a particular part of the page. If the generated script does not include a hover action, you will need to add the code to move the mouse pointer. There are two ways you might be able to resolve this issue:

  1. Re-record the transaction and try clicking the element, not just hovering over it. Many pages will handle clicks and hovers the same way, though some might handle them differently.

  2. Use the moveMouseInto function from moveMouseIntoElement.js in the transaction scripting examples repository to move the mouse pointer to a specific element and trigger hover events.

TimeoutError: Transaction timed out

This error occurs when the configured test timeout is reached before the script has completed. To prevent this error, you can increase the test timeout or reduce the runtime of the script. For example, you can make the script run faster by minimizing or removing use of driver.sleep. If your transaction is lengthy or complex with lots of steps, consider breaking it down into two or more separate transactions.

The maximum configurable timeout is dependent on the test interval:

  • 60 seconds for 2 minute tests

  • 150 seconds for 5 minute tests

  • 180 seconds for 10+ minute tests

To configure the timeout in the ThousandEyes platform, go to the Test Settings page, find and expand the test in the list, and adjust the Timeout slider in Transaction Timing section of the Advanced Settings tab.

Validate

It is important to validate that the transaction runs successfully on the agents in the platform. A script that works in one browser session or from one network location can still fail from the Cloud or Enterprise Agents that run the scheduled test. Run an actual transaction instant test before you enable or rely on the scheduled test.

After you create or update your test, click Run Once to run an instant test in a new browser tab. Wait for the test results and then verify that all of the agents successfully completed the transaction. If any errors occur, click the Run Again link above the timeline in the view to determine if the error is consistent or intermittent. Then, see the troubleshooting section to determine the cause of the error.

My Script Works Locally, but Fails in the Platform. Why?

User Agent: The default curl user agent we use for HTTP tests is rejected by many larger sites. You should supply a chrome user agent or similar so that all layers use the same UA. You can configure the user agent in the HTTP Request section of the Advanced Settings tab in the test's settings.

Agent Location: Scripts that work fine locally might fail on agents in other regions, as they might be routed differently or land on different sites. Make sure you rule out any location-specific issues.

Agent Network Conditions: The time that network requests take can have an impact on whether your script works or not. For example, if you have a driver.sleep command that waits for 5 seconds, that might work for you but not be sufficient for an agent in a distant region. It's best to not use hard-coded sleep values, but instead use waits with sufficient timeouts.

Authentication: If you test an application that uses Integrated Windows Authentication (IWA), the browser might authenticate you automatically while you record the flow. IWA, sometimes called "silent authentication", uses your operating system credentials to automatically authenticate to a web server without an interactive login form. IWA is commonly used for internal applications or intranet sites, but might also be used with SaaS applications when they are configured with federated single sign-on.

If IWA changes the workflow that Google Chrome Recorder captures, and your organization allows it, launch a separate Chrome instance before recording. The following Windows commands start Chrome with a fresh temporary profile, block the normal integrated authentication allowlist, disable extensions, and skip first-run screens.

Command Prompt:

PowerShell:

Network Security: When the transaction runs on the agent, it is almost always from a different network than where it was originally recorded. This can cause different firewall or proxy rules to apply and block the traffic coming from the agent. If the transaction test works locally but fails in the ThousandEyes platform, you should check the network layer metrics and path visualization to ensure the agent is able to reach the target. For Enterprise Agents, you might need to configure a proxy or verify that the necessary firewall rules are in place.

Using the Transaction Test View

After you create or update a Transaction test, you can see the test data under Network & App Synthetics > Views. The Transaction view leverages the ThousandEyes standard layout, documented here. For general information on the ThousandEyes standard view layout, see Getting Started with Views. This section highlights specifics shown in the Transaction view.

Transaction View, Timeline

The Transactions view, showing the timeline

The top of the Transaction view shows a timeline similar to other views, with a time period slider below. Three metrics can be displayed on the timeline:

  • Transaction Time (default): The amount of time spent running the transaction test. When Transaction Time is selected, you might also select up to three markers to view on the timeline

  • Errors: The number of timeout errors, page errors, assert errors, and other errors that occurred in the test round

  • Completion: Whether or not the transaction completed without errors

When a single agent is selected, you can mouse over the error indicator in the swimlane under the timeline to view the specific error details.

Transaction View, Map

The Transactions view's map tab, showing global results from agents running tests

The Map tab as shown below displays a global map showing all of the agents that are running the test, with a Metrics panel to summarize data and any error messages reported by the agents. Clicking on an agent in the map will select that agent in the Agent selector above the timeline. The color of the agents shown on the map indicates the speed relative to the test duration, as specified by the Timeout parameter in the Advanced Settings tab for the test configuration in Network & App Synthetics > Test Settings.

The Metrics panel shows the transaction time (average, when all agents are selected) and when a single agent is selected also shows the individual marker times.

The Metrics panel, showing global agents' transaction times

Transaction View, Table

The Transaction view's Table tab, showing test results from selected test rounds

The Table tab shows test details from the selected test round for each agent. If any errors occur during the transaction, the agent will be shown in the table with a red dot next to its name. You can mouse over this icon to view specific error details. Clicking on an agent in the table will select that agent in the Agent selector above the timeline.

For more details on the transaction view table, see the Transaction Test Table Tab View article.

Transaction View, Waterfall

The Transaction view's Waterfall tab, showing details about pages, markers, and screenshots

The Waterfall tab in the transaction view is similar to the Waterfall tab in the page load view, with three additional features at the top of the chart:

  • Pages: Because transaction tests can navigate through more than one page, the waterfall chart in the transactions view indicates each page that is visited and the duration of time spent on that page. You can mouse over a page in the Page row to view the page's duration. You can click a page to filter the waterfall chart to only include components from that page.

  • Markers: Markers are exclusive to transaction tests. The waterfall chart for transactions includes a visualization of the marker timings over the duration of the transaction. You can mouse over a marker in the Markers row to view the marker's exact timing. You can click a marker to filter the waterfall chart to only include components during that marker.

  • Screenshots: Up to 12 screenshots captured during the transaction will be stored with the test data and displayed on the Waterfall tab. You can mouse over the picture icon in the Screenshots row to view the captured screenshot. The horizontal position of the icon in the row indicates the relative point in time during the transaction that the screenshot was captured.

For complete details on the Waterfall tab, see the Navigating Waterfall Charts for Page Load and Transaction Tests article.

Resources

ThousandEyes Product Documentation

External Resources

Last updated