Browser Tests
Security Monitoring is now available Security Monitoring is now available

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, and from multiple devices. These tests verify both that your applications are up and responding to requests, and that any conditions defined in your scenarios are met.


Test details

Define the configuration of your browser test.

  1. Starting URL: The URL from which your browser test starts the scenario.

    • Advanced Options (optional): Set custom request headers, cookies, or authenticate through Basic Auth.
      • Headers: Defined headers override the default browser headers. For example, set the User Agent in the header to identify Datadog scripts.
      • Authentication: Authenticate through HTTP Basic Authentication with a username and a password.
      • Cookies: Defined cookies are added to the default browser cookies. Set multiple cookies using the format <COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.
  2. Name: The name of your browser test.

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

  4. Devices: The devices to run your test on. Available devices are Laptop Large, Tablet, and Mobile Small.

  5. Locations: The Datadog managed locations to run the test from. Many AWS locations from around the world are available. You can also set up a Private Location to run a Synthetic Browser test on a private URL not accessible from the public internet.

  6. How often should Datadog run the test? Intervals are available between every 5 minutes to once per week.

Use global variables

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

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 <INSERT_NUMBER> minutes from any <INSERT_NUMBER> of <NUMBER_OF_CHOSEN> 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 using.
  • Retry <INSERT_NUMBER> 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 via 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 VariableDescription
    {{#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.

  5. Record your test.

Record test

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 in order to avoid sizing issues in the displayed window within Datadog’s interface. Hitting Open in a pop-up and Shift opens the pop up in incognito mode. This is useful 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. Your actions are recorded and used to create steps within your browser test scenario.
  4. Use the steps available in the upper left corner to enrich your scenario:

    Note: Your last browser test step must be 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.


After saving a browser test, you can record steps which you can then edit or build on.

Steps are a series of actions that you can record for a browser test which you can then edit or build on. You can define the steps you want your browser test to go through either by directly recording them with the Datadog test recorder extension or by manually adding the step of interest. You can also configure certain steps with advanced options.

Further Reading