Advanced Options for Browser Test Steps

Advanced Options for Browser Test Steps

User specified locator

By default, browser tests use the Datadog locator system. It is recommended to only use custom selectors in edge cases as the Datadog locator system is what allows tests to be self-maintaining.

Custom selectors are created by performing a step of interest in the recorder (click, hover, assert, etc.) on any element of your page. This specifies the kind of step that needs to be performed.

To specify your custom locator:

  • Record or manually add a step to your recording.
  • Click on the recorded step and click Advanced options.
  • The HTML element can then be selected either with an X-path or with a CSS class/ID, for example: div, h1, or .hero-body.
  • Once you have defined an element, click Test to highlight the element in the recording on the right.

By default the box If user specified locator fails, fail test is selected. This means that, by default, if the defined locator fails, the test is considered a failure.

You can decide to fall back on the regular browser test algorithm by deselecting the If user specified locator fails, fail test box.


If a browser test is not able to locate an element, by default it retries the step for 60 seconds.

You can decide to decrease or increase this time out up to 300 seconds if you want your test to wait for less or more time to be able to find the step targeted element.

Optional step

In some cases, such as in the event of a pop-up, you may want to make some steps optional. To configure this option, select Allow this step to fail. If the step fails after the amount of minutes specified on the timeout option (60 seconds by default), then the test will move on and execute the next step.

Prevent screenshot capture

You can prevent a step screenshot from being captured at test execution. 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.

Note: This feature is also available at the global test level, as an advanced option in your browser test configuration.


Subtests advanced options also allow you to choose where you want your subtest to be played:

  • Main (default): Subtest is played in your main window, in sequence with other steps.
  • New: Subtest is played in a new window, which is closed at the end of the subtest. This means the window cannot be reused.
  • Specific window: Subtest is played in a numbered window, which can be reused by other subtests.

Opening your subtest in the main window means that your subtest is the continuation of your main test as it uses the URL from the previous step. Opening your subtest in a new window, or in a specific window, means that the test starts running from the subtest start URL.

Further Reading

Additional helpful documentation, links, and articles: