Browser Test Steps

Browser Test Steps

Overview

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. All steps come with a set of advanced options that you can configure.

Note: The default timeout for each step is approximately 60 seconds. You can override this default timeout through the dedicated advanced option.

Automatically recorded steps

The following steps are automatically recorded with the Datadog browser test recorder extension:

Click

Datadog browser test recorder extension automatically records clicks on your page. Specify the type of click you want your browser test to perform at execution time:

Choose from:

  • Primary click (corresponds to a left click)
  • Double click
  • Contextual click (corresponds to a right click)

Type text

Datadog browser test recorder extension automatically records text inputted in any fields of your website (forms, text areas, etc.):

Select option

Datadog browser test recorder extension automatically records options being selected from select dropdown menu:

Upload file

You can record the uploading of files as a step. To record an Upload step you can:

  • Either open your desktop from the browser,
  • Or drag and drop your file in the recording iframe.

This is limited to 10 files with a limit of 5MB each.

Manually added steps

The following steps can be manually added to a browser test by configuring them on the the browser test recorder page:

Assertion

Assertions allow you to validate that your browser test is in the state you expect it to be in, at any given point of a simulated user journey. This is why you must end your browser tests by an Assertion to confirm it ended up in an expected state.

Some assertions are performed on the active page. Active page refers to the page that has experienced the last interaction like using a Click or an Assertion on a given page element for instance.

Test an element’s content

Selects an element and checks if it contains a specific value. For instance, you could select a div and check whether it contains the word “hello”.

Test an element’s attribute

Selects an element of your page and checks if one of its attributes matches the expected content. For instance, you could test that an src attribute value matches the path of the expected image.

Test that some text is present on the active page

Asserts that some specific text is present on the current page.

Test that some text is not present on the active page

Asserts that some specific text is NOT present on the current page.

Test the content of the URL of the active page

Takes the URL of the last page that was interacted with, then asserts whether a specific value (string, number, regex) is present within it.

Test that an element is present on the active page

Asserts that an element (such as a specific span, div, h, a, etc.) is present on the current page.

Test that an email was received

Asserts that an email was sent and whether specific values (string, number, regex) are present within the email subject or body. This assertion leverages email variables, you consequently first need to create an email variable to be able to use a Test that an email was received assertion.

Test your UI with custom JavaScript

Test a custom assertion on the active page using your own JavaScript code.

Note: JavaScript assertions support both synchronous and asynchronous code.

The JavaScript assertion function comes with the following parameters and requires a return statement.

  • The return (mandatory) statement should reflect the condition the assertion needs to meet for your browser test step to be successful. Any type can be returned, but the value is automatically casted as a boolean.

  • vars (optional): A string containing your browser test variables. Use vars.<YOUR_VARIABLE> to refer to a browser test variable in your JavaScript snippet. For example, if your browser test contains a USERNAME variable, call it in your JavaScript snippet using vars.USERNAME.

  • element (optional): The locator of the element on the page. To set this up, use the Select and Update target element buttons. The selected element automatically leverages Datadog’s browser test multi-locating algorithm.

Since JavaScript assertions run in the context of the active page, these steps can access all the objects defined in the active page (libraries, built-ins, global variables, etc.). To load external libraries, use a promise. For example:

const script = document.createElement('script');
script.type = 'text/javascript';
script.src = "https://code.jquery.com/jquery-3.5.1.slim.min.js";
const promise = new Promise((r) => script.onload = r)
document.head.appendChild(script)

await promise

// Script is now loaded

return jQuery().jquery.startsWith('3.5.1')

Note: The way Browser tests load external JavaScript is by adding it to the page, so it will only work if your website accepts it.

Test a downloaded file

Perform verifications on files downloaded in previous steps. You can check that a file was correctly downloaded and assert on: the file name, size, and MD5 value.

Note: You can find out more on how to test downloads on this dedicated guide.

Refresh a page

Refresh the current page of the scenario.

This step allows you to access unique Synthetic mail inboxes after creating an email variable. Choose the email you are interested in and click the link you want your browser test to click on. This step brings your test to the corresponding page and allows you to move on with the rest of your journey from that specific page.

Go to a specific page.

Note: You must prepend your URLs with http or https in the Enter link URL box.

Special actions

The Datadog browser test recorder extension is able to record most steps associated to user journeys you might want to monitor. However, some steps—such as Hover, Press Key, and Scroll—are not recorded automatically. Explicitly add a step for them using the Special Actions menu located at the top left-hand corner of the recorder.

Hover

To avoid generating a step at each element hovering during recording, this browser test step is not added through an actual hovering mechanism but using a dedicated step with a click.

After selecting the Hover step, click on the element you want to choose to create a new step.

Press key

You can simulate users entering keystrokes using Press Key steps. The keys below can be recorded using the Datadog browser test recorder extension:

  • Enter
  • Arrows (up, down, right, and left)
  • Tab (outside a form)
  • Escape
  • Backspace

To press keys that are not being automatically recorded, specify which values need to be pressed in the value box of the Press Key special step:

The below modifiers can also be applied to the inputted value:

  • Alt
  • Control
  • Meta
  • Shift

Scroll

Browser tests automatically scroll to the element they need to interact with. Consequently, in most cases, you do not need to manually add a scroll step. The scroll step should only be added when needed to trigger an additional network request, such as in an infinite scroll.

You need to specify the number of pixels your browser test should scroll vertically or horizontally.

By default, the Scroll step scrolls on the whole page. If you need to scroll on a specific element (for instance a specific <div>), use the Target Element option to select the element you want your browser test to scroll on.

Wait

By default, Datadog waits for a page to be fully loaded before performing a step or a next step—with a timeout of 60 seconds. If you know a page or page element is taking more than 60 seconds to load, you can customize that timeout in the advanced options of your step or add a hardcoded wait step (max value of 300 seconds).

Note: This additional time is systematically added to each run of your browser test scenario.

Variable

To create a variable, first give it a name then define its value using one of the below methods. To learn how to use variables inside of your steps, see Using variables.

Pattern

Create a variable by defining its value from one of the below available builtins:

{{ 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, format) }}
Generates a date in one of our accepted formats with a value of the date the test is initiated + n days.
{{ timestamp(n, unit) }}
Generates a timestamp in one of our accepted units with a value of the timestamp the test is initiated at +/- n chosen unit.

Element

Create a variable out of a span, div, etc. content by extracting the text of this element.

JavaScript

Write the custom JavaScript code returning the value you want your variable to be assigned to.

Note: JavaScript steps support both synchronous and asynchronous code.

The JavaScript function comes with the following parameters and requires a return statement.

  • The return (mandatory) statement should return the value you want to associate to your JavaScript variable. Any type can be returned, but the value is automatically casted as a string.

  • vars (optional): A string containing any existing browser test variables you would want to leverage inside of your code. Use vars.<YOUR_VARIABLE> to refer to a browser test variable in your JavaScript snippet. For example, if your browser test already features a PRICE variable, call it in your JavaScript snippet using vars.PRICE.

  • element (optional): The locator of the element on the page. To set this up, use the Select and Update target element buttons. The selected element automatically leverages Datadog’s browser test multi-locating algorithm.

Since JavaScript assertions run in the context of the active page, these steps can access all the objects defined in the active page (libraries, built-ins, global variables, etc.). To load external libraries, use a promise, for example:

const script = document.createElement('script');
script.type = 'text/javascript';
script.src = "https://code.jquery.com/jquery-3.5.1.slim.min.js";
const promise = new Promise((r) => script.onload = r)
document.head.appendChild(script)

await promise

// Script is now loaded

return jQuery().jquery.startsWith('3.5.1')

Note: The way Browser tests load external JavaScript is by adding it to the page, so it will only work if your website accepts it.

Global variable

Pick any global variables defined in Synthetic Monitoring Settings.

Global variable - MFA

Pick any MFA global variables defined in Synthetic Monitoring Settings.

This type of global variable stores time-based one time password (TOTP) secret keys, allowing you to test your MFA modules and MFA-protected workflows.

For more information about TOTP-based MFA in a browser test, see this TOTP guide.

Email

Generate a random Synthetic email address that can be used in your test steps to assert if an email was correctly sent or to navigate to a link contained within the email (e.g. click a confirmation link). A unique mailbox is generated at each test execution to avoid any conflicts between test runs.

Subtests

You can run browser tests within other browser tests in order to reuse existing workflows (up to two levels of nesting). Find out more about why you should use subtests and see some examples in this dedicated guide.

Variables from subtests can be overriden in parent tests if you ensure the variables created at the parent test level have the same names as the variables present in the subtest. By default, the subtest is executed in sequence with the previous steps of the parent test but this can be tweaked using Subtest Advanced options.

Note: If it does not make sense for you to run your subtest independently, you can pause it. It will continue to be called as part of your main test, but it will not be executed individually.

HTTP requests

You can run HTTP requests as part of your browser tests.

Set up

To define your HTTP request:

  1. Choose the Method and URL to query. Available methods include GET, POST, PATCH, PUT, HEAD, DELETE, and OPTIONS.
  2. Optionally specify Advanced Options:
    • Follow redirects: Toggle to have the monitored endpoint follow up to ten redirects.
    • Allow insecure certificates: Toggle to have your HTTP test continue the connection even if there is an error when validating the certificate.
    • Headers: Defined headers override the default browser headers.
    • Authentication: HTTP basic authentication with username and password
    • Body: Request body and body type (text/plain, application/json, text/xml, text/html, application/x-www-form-urlendcoded, or None). Note: The request body is limited to a maximum size of 50 kilobytes.
    • Cookies: Defined cookies are added to the default browser cookies. Set multiple cookies using the format <COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.
  3. Click Test URL to test your request configuration. This results in a preview showing response data.

Add assertions

Optionally, you can base your step success on assertions about the defined HTTP request:

TypeOperatorValue type
bodycontains, does not contain, is, is not,
matches, does not match,
jsonpath, xpath
String
Regex
String, Regex
headercontains, does not contain, is, is not,
matches, does not match
String
Regex
response timeis less thanInteger (ms)
status codeis, is notInteger

If you click Test URL, the basic assertions are automatically filled:

  • Response time is less than 2000 ms
  • Header content-type is “returned value”
  • Status code is “returned value”

Extract a variable from the response

You can also optionally extract a variable from the response of your HTTP request by parsing its response headers or body. The value of the variable is updated each time the HTTP request step is being run.

To parse your variable:

  1. Enter a Variable Name. Your variable name can only use uppercase letters, numbers, and underscores and must have at least three characters.

  2. Decide whether to extract your variable from the response headers, or from the response body:

    • Extract the value from response header: use the full response header of your HTTP request as the variable value or parse it with a regex.
    • Extract the value from response body: use the full response body of your HTTP request as the variable value, parse it with a regex, a JSONPath, or a XPath.

Once created, this variable can be used in the following steps of your browser test.

Using variables

On manually added steps

All step input fields with a {{ indication support variables:

To see all available variables, type {{ in the input field and choose your variable of interest.

On automatically recorded steps

If you want to record a step leveraging a variable, you can use the little hand on your variable box:

At recording, this translates into the actual value of the variable being injected on your website’s input (consequently allowing you to move on with the rest of your steps) and creates an associated Type text step featuring {{ <YOUR_VARIABLE_NAME> }}. At test execution, {{ <YOUR_VARIABLE_NAME> }} is systematically replaced by your variable’s associated value.

Some variables only get computed at runtime (for example, a variable from HTTP request or from JavaScript step). To record a step using one of these variables, record a step with the actual variable value, then replace the actual value with {{ <YOUR_VARIABLE_NAME> }} on your step definition before saving your test.

Note: If a variable gets assigned different values along your browser test steps (for example, across subtests), the variable systematically uses the value that was first assigned to it.

Further Reading

Additional helpful documentation, links, and articles: