Browser Tests

Browser Tests


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.

Are you interested in testing applications that sit behind MFA? Read our dedicated guide and send us feedback to help us work on the systems that matter the most to your teams.

Test configuration

Define the configuration of your browser test.

  1. Starting URL: The URL from which your browser test starts the scenario.
  2. Advanced Options (optional): Set specific options to your browser test:
  • Headers: Define headers to add to or override the default browser headers. For example, set the User Agent in the header to identify Datadog scripts.
  • Authentication: Authenticate through HTTP Basic, Digest or NTLM with a username and a password. Credentials added to the HTTP Auth fields are used on every step of your browser test.
  • Cookies: Define cookies to add to the default browser cookies. Set multiple cookies using the format <COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.
  • Proxy URL: URL of the proxy the requests should go through (http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT>).

Note: These 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 be active to record following steps, you can manually apply these options on the page you are recording from and then create subsequent steps for your test.

  • Do not capture any screenshots for this test: Select this option to prevent any screenshot from being taken for all your test steps. This option is also available as an advanced option at the individual step level. This is helpful to ensure no sensitive data gets featured in your test results. Use mindfully as it can make failure troubleshooting more difficult. Read more about security recommendations here.
  1. Name: The name of your browser test.
  2. Select your tags: The tags attached to your browser test. Use the <KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY> on the Synthetic tests page.
  3. Browsers & Devices: The browsers (Chrome, Firefox, Edge) and devices (Laptop Large, Tablet, Mobile Small) to run your test on.
  4. Locations: The Datadog managed locations to run your test from. Many AWS locations from around the world are available for each site. You can also set up private locations to run your browser test from custom locations or from inside private networks. See a full list of locations in the Datadog app or use the API.

    Note: The West US (AWS GovCloud) location is supported on the Datadog for Government site.

  5. How often should Datadog run the test? Intervals are available between every five minutes to once per week. The one minute frequency is available upon request.

Use global variables

You can use the global variables defined in the Settings in the Starting URL as well as in the Advanced Options of your browser tests. To display your list of variables, type {{ in the desired field.

To use global variables in your browser test’s recording, navigate to your recorded steps and click + Variables below the Start Recording button. Select Global Variable from the dropdown menu.

Search for available global variables and click + to add them to your recording panel. When you are done adding global variables, click OK.

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

Notify your team

A notification is sent according to the set of alerting conditions. To configure your notifications:

  1. Enter a message for the browser test. This field allows standard Markdown formatting and supports the following conditional variables:

    Conditional Variable Description
    {{#is_alert}} Show when monitor alerts
    {{^is_alert}} Show unless monitor alerts
    {{#is_recovery}} Show when monitor recovers from either ALERT
    {{^is_recovery}} Show unless monitor recovers from either ALERT

    Notification messages include the message defined in this section and information about the failing locations.

  2. Choose your services and/or team members to notify.

  3. Specify a renotification frequency. To prevent renotification on failing tests, leave the option as Never renotify if the monitor has not been resolved.

  4. Click Save Details and Record Test.

Record your steps

Tests can be only recorded from Google Chrome. To record your test, download the Datadog Record Test extension for Google Chrome.

  1. 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 in Incognito mode to start recording your test from a fresh browser free from already logged in sessions, cookies from your existing browser, etc.

  2. Click on Start recording to begin recording your browser test.

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

  4. In addition to the automatically recorded steps, you can also use the steps available in the upper left corner to enrich your scenario:

    Note: You should always make sure to end your browser test with an assertion to confirm the journey executed by the browser test resulted in the expected state.

  5. Once you have finished your scenario, click on Save and Launch Test.


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 have access to the custom role feature, add your user to any custom role that includes synthetics_read and synthetics_write permissions.

Further Reading