Browser tests are scenarios executed by Datadog on your web applications. They run at configurable periodic intervals from multiple locations around the world, from multiple browsers, and devices. These tests verify both that your applications are up and responding to requests, and that any conditions defined in your scenarios are met.
If you are interested in testing applications that sit behind MFA, read the dedicated guide and send feedback to the Synthetic Monitoring team to help improve the systems that matter most to your teams.
Test configuration
Define the configuration of your browser test.
Enter a Starting URL: The URL from which your browser test starts the scenario.
Select environment and additional tags: Set the env and related tags attached to your browser test. Use the <KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY>.
Select browsers and devices: The browsers (such as Chrome, Firefox, and Edge), and devices (such as Laptop Large, Tablet, and Mobile Small) to run your test on.
For a large laptop device, the dimensions are 1440 pixels x 1100 pixels.
For a tablet device, the dimensions are 768 pixels x 1020 pixels.
For a small mobile device, the dimensions are 320 pixels x 550 pixels.
Select managed and private locations: Select locations around the world that are managed by Datadog or create private locations to run your browser test from custom locations or inside private networks.
Datadog’s out-of-the-box managed locations allow you to test public-facing websites and endpoints from regions where your customers are located.
Americas
APAC
EMEA
Canada Central (AWS)
Hong Kong (AWS)
Cape Town (AWS)
Northern California (AWS)
Mumbai (AWS)
Frankfurt (AWS)
Northern Virginia (AWS)
Seoul (AWS)
Ireland (AWS)
Ohio (AWS)
Singapore (AWS)
London (AWS)
Oregon (AWS)
Sydney (AWS)
Paris (AWS)
São Paulo (AWS)
Tokyo (AWS)
Stockholm (AWS)
Virginia (Azure)
Osaka (AWS)
Milan (AWS)
Jakarta (AWS)
Bahrain (AWS)
The Datadog for Government site (US1-FED) uses the following managed location:
Americas
US-West
You can also use the Continuous Testing Tunnel to trigger tests on your local development setup or in your CI/CD pipeline to test internal environments.
Set the test frequency: The intervals vary from every five minutes to once per week. To request one-minute frequency, contact Support.
Snippets
When setting up a new Synthetic Monitoring browser test, use snippets to automatically fill in your devices and regions, rather than selecting these options manually. The following snippets are available:
Screen sizes: Automatically perform your browser tests on a specifically sized screen across browsers:
Large
Tablet
Mobile
Multi-region check: Automatically test your website against a location in each of the three primary geographic regions (AMER, APAC and EMEA).
Advanced options
Select Disable CORS to prevent the cross-origin resource sharing (CORS) policy from blocking your test. To prevent the Content Security Policy (CSP) from blocking your test, select Disable CSP.
Request Headers: Define headers in the Name and Value fields to add to or override the default browser headers. For example, you can set the User Agent in the header to identify Datadog scripts.
Cookies: Define cookies to add to the default browser cookies. Enter one cookie per line, using the syntax of Set-Cookie.
HTTP Authentication: Authenticate through HTTP Basic, Digest, or NTLM with a username and a password. Your credentials are used in every step of your browser test. Note: Authentication through HTTP Basic can be used for websites that request user credentials through a browser system prompt.
Request options are set at every test execution and apply to every step of your browser test at execution time, not recording time. If you need these options to remain active to record the following steps, manually apply the options on the page you are recording from and create subsequent steps in your test.
Select Ignore server certificate error to instruct the test to skip errors in the server certificate.
Client Certificate: Perform tests on systems that require client certificates by clicking Upload File and uploading your certificate file and private key. Only PEM certificates are accepted.
Client Certificate Domains: Once the certificate files are uploaded, the client certificate applies to the starting URL’s domain. To apply the client certificate on another domain, specify the domain in the Value field.
You can include wildcards in the URL.
Enter a URL for a proxy you want to send requests through in the Proxy URL field as http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT>.
Select Do not capture any screenshots for this test to prevent screenshots from being taken in your test steps.
This privacy option is available as an advanced option at the individual test step level and ensures that no sensitive data appears in your test results. Preventing the test from taking screenshots makes troubleshooting failures more difficult. For more information, see Data Security.
Enter an amount of time in seconds for the test to wait before declaring the initial test step as failed.
By default, timezone is set to UTC, and language is set to English (en). To define a language, use the corresponding 2 or 3 digit ISO code.
Create local variables
To create a local variable, click Create a Local Variable. You can select one of the following available builtins to add to your variable string:
{{ numeric(n) }}
Generates a numeric string with n digits.
{{ alphabetic(n) }}
Generates an alphabetic string with n letters.
{{ alphanumeric(n) }}
Generates an alphanumeric string with n characters.
{{ date(n unit, format) }}
Generates a date in one of Datadog’s accepted formats with a value corresponding to the UTC date the test is initiated at + or - n units.
{{ timestamp(n, unit) }}
Generates a timestamp in one of Datadog’s accepted units with a value corresponding to the UTC timestamp the test is initiated at +/- n units.
{{ uuid }}
Generates a version 4 universally unique identifier (UUID).
{{ public-id }}
Injects the Public ID of your test.
{{ result-id }}
Injects the Result ID of your test run.
To obfuscate local variable values in test results, select Hide and obfuscate variable value. Once you have defined the variable string, click Add Variable.
Use global variables
You can use the global variables defined in Settings in the Starting URL and Advanced Options of your browser test details, as well as in your test recording.
To display a list of available variables:
In your browser test’s details: Type {{ in the desired field.
In your browser test’s recorder: Import the variable in your test, then type {{ in the desired field or inject the variable in your application to use it.
For more information about using variables in your browser test recording, see Browser Test Steps.
Define alert conditions
You can customize alert conditions to define the circumstances under which you want a test to send a notification alert.
An alert is triggered if any assertion fails for X minutes from any n of N locations. This alerting rule allows you to specify for how much time and in how many locations a test needs to fail before triggering the notification.
Retry X times before location is marked as failed. This allows you to define how many consecutive test failures need to happen for a location to be considered as failed. By default, there is a 300ms wait before retrying a test that failed. This interval can be configured with the API.
Configure the test monitor
A notification is sent according to the set of alerting conditions. Use this section to define how and what to message your teams.
Show when the monitor matches priority (P1 to P5).
{{^is_priority}}
Show unless the monitor matches priority (P1 to P5).
Notification messages include the message defined in this section and information about the failing locations.
Choose team members and services to notify.
Specify a renotification frequency. To prevent renotification on failing tests, leave the option as Never renotify if the monitor has not been resolved.
Click Save Details and Record Test to save your test configuration and record your browser steps.
You can switch tabs in a browser test recording in order to perform an action on your application (such as clicking on a link that opens another tab) and add another test step. Your browser test must interact with the page first (through a click) before it can perform an assertion. By recording all of the test steps, the browser test can switch tabs automatically at test execution.
Optionally, select Open in a pop-up at the upper right of the page to open your test recording in a separate pop-up window. This is useful if your application does not support being opened in an iframe or if you want to avoid sizing issues at recording. You can also open the pop-up in Incognito mode to start recording your test from a fresh browser free from already logged-in sessions, cookies from your existing browser, and more.
Optionally, enable Datadog to automatically collect RUM data when running step recordings from your browser test. For more information, see Explore RUM & Session Replay.
Click Start Recording to begin recording your browser test.
As you click on your application going through the user journey you want to monitor, your actions are automatically recorded and used to create steps within your browser test scenario on the left.
In addition to the automatically recorded steps, you can also use the steps available in the upper left corner to enrich your scenario:
Datadog recommends ending your browser test with an assertion to confirm the journey executed by the browser test resulted in the expected state.
Once you have finished your scenario, click Save and Launch Test.
Permissions
By default, only users with the Datadog Admin and Datadog Standard roles can create, edit, and delete Synthetic browser tests. To get create, edit, and delete access to Synthetic browser tests, upgrade your user to one of those two default roles.
If you are using the custom role feature, add your user to any custom role that includes synthetics_read and synthetics_write permissions.
Restrict access
Access restriction is available for customers using custom roles on their accounts.
You can restrict access to a browser test based on the roles in your organization. When creating a browser test, choose which roles (in addition to your user) can read and write your test.
Further Reading
Additional helpful documentation, links, and articles:
