Overview Open Chrome DevTools Simulate mobile devices with Device Mode Performance insights: Get actionable insights on your website's performance Animations: Inspect and modify CSS animation effects Changes: Track your HTML, CSS, and JavaScript changes Coverage: Find unused JavaScript and CSS CSS Overview: Identify potential CSS improvements Issues: Find and fix problems Media: View and debug media players information Memory Inspector: Inspect ArrayBuffer, TypedArray, DataView, and Wasm Memory. Network conditions: Override the user agent string Security: Understand security issues Search: Find text across all loaded resources WebAuthn: Emulate authenticators
Overview Open Chrome DevTools Simulate mobile devices with Device Mode Performance insights: Get actionable insights on your website's performance Animations: Inspect and modify CSS animation effects Changes: Track your HTML, CSS, and JavaScript changes Coverage: Find unused JavaScript and CSS CSS Overview: Identify potential CSS improvements Issues: Find and fix problems Media: View and debug media players information Memory Inspector: Inspect ArrayBuffer, TypedArray, DataView, and Wasm Memory. Network conditions: Override the user agent string Security: Understand security issues Search: Find text across all loaded resources WebAuthn: Emulate authenticators

Recorder features reference

Published on

Discover ways to share user flows, edit them and their steps in this comprehensive features reference of the Chrome DevTools Recorder panel.

To learn the basics of working with the Recorder panel, see Record, replay, and measure user flows.

Edit user flows

DevTools Recorder panel has a drop-down menu in the header which allows you to select a user flow to edit.

On the top of the Recorder panel, there are options for you to:

  1. Add a new recordingAdd.. Click on the + icon to add a new recording.

  2. View all recordingsExpand more.. The drop-down shows the list of saved recordings. Select the [number] recording(s) option to expand and manage the list of saved recordings. View all recordings.

  3. Export a recordingFile download.. To further customize the script or share it for bug reporting purposes, you can export the user flow in one of the following formats:

    For more information on the formats, see Export a user flow.

  4. Import a recordingFile upload.. Only in JSON format.

  5. Delete a recordingDelete.. Delete the selected recording.

You can also edit the recording's name by clicking the edit button Edit. next to it.

Share user flows

You can export and import user flows in the Recorder. This is useful for bug reporting because you can share an exact record of the steps that reproduce a bug. You can also export and replay it with external libraries.

Export a user flow

To export a user flow:

  1. Open the user flow you want to export.
  2. Click on the ExportFile download.. button at the top of the Recorder panel. Download format options.
  3. Select one of the following formats from the drop-down list:
    • Export as a JSON file. Download the recording as a JSON file.
    • Export as a @puppeteer/replay script. Download the recording as a Puppeteer Replay script.
    • Export as a Puppeteer script. Download the recording as a Puppeteer script.
  4. Save the file.

You can do the following with each export option:

  • JSON: Edit the human-readable JSON object and import the JSON file back to the Recorder.
  • @puppeteer/replay: Replay the script with the Puppeteer Replay library. When exporting as a @puppeteer/replay script, the steps remain a JSON object. This option is perfect if you want to integrate with your CI/CD pipeline but still have the flexibility to edit the steps as JSON, later convert and import them back into the Recorder.
  • Puppeteer script: Replay the script with Puppeteer. Since the steps are converted into JavaScript, you can have more fine-grained customization, for example, looping the steps. One caveat, you can't import this script back into the Recorder.

Export in a custom format by installing an extension

Note: This feature is available from Chrome version 104.

You can install a Chrome extension to export replay scripts in your favorite format.

Custom extension for the Recorder panel.

For example:

Troubleshooting

If you don't see the export option after installing the extension, do the following:

  • The extension only works on web pages. For example, the export option is not available for chrome:// pages like chrome://extensions.
  • Always open a new browser tab after installing the extension.
  • There is an issue in Chrome 104 and 105 that prevents the export option showing if you open the Recorder as the first DevTools panel. As a workaround, open another panel (for example, Console) first before opening the Recorder. The issue is fixed in Chrome 106.
Gotchas

Advanced use case: Build an extension

You can build your own Recorder extension too. See the Recorder extension API documentation to learn how to build one.

You can also refer to this extension example and install it following the steps outlined in the documentation.

Import a user flow

To import a user flow:

  1. Click the ImportFile upload. button at the top of the Recorder panel. Import recording.
  2. Select the JSON file with the recorded user flow.
  3. Click the Replay.Replay button to run the imported user flow.

Replay with external libraries

The Puppeteer Replay is an open source library maintained by the Chrome DevTools team. It is built on top of Puppeteer. It is a command line tool, you can replay JSON files with it.

Apart from that, you can transform and replay JSON files with the following 3rd party libraries.

Transform JSON user flows to custom scripts:

Replay JSON user flows:

Gotchas

Advanced use case: Integrate with the Puppeteer Replay library

Similar to the 3rd party libraries above, you can build your own library on top of the Puppeteer Replay too. The Puppeteer Replay library provide ways for you to customize how a recording is run and "stringify" the user flow JSON files, that is, convert them to something else.

Debug user flows

Like any code, sometimes you have to debug the recorded user flows.

To help you debug, the Recorder panel lets you slow down the replays, set breakpoints, and step through the execution.

Slow down the replay

By default, the Recorder replays the user flow as fast as it can. To understand what happens in the recording, you can slow down the replay speed:

  1. Open the Replay.Replay drop-down menu.
  2. Choose one of the replay speed options:
    • Normal (Default)
    • Slow
    • Very slow
    • Extremely slow
Slow replay.
Gotchas

You can use these slow replay options only in the Recorder. To add timeouts to the recording itself, see Adjust timeouts for steps.

Set breakpoints and execute step by step

To set a breakpoint and execute step by step:

  1. Hover over the Step. circle next to any step in a recording. The circle turns into a Breakpoint. breakpoint icon.
  2. Click the Breakpoint. breakpoint icon and replay the recording. The executions pauses at the breakpoint. Execution pause.
  3. To step through the execution, click the Execute one step. Execute one step button on the action bar at the top of the Recorder panel.
  4. To stop the replay, click Pause. Cancel replay.

Edit steps

You can edit any step in the recording by clicking the Expand. button next to it.

You can also add missing steps and remove accidentally recorded ones as described below.

Add steps

Sometimes, you may need to add steps manually. For example, the Recorder doesn't automatically capture hover events because this pollutes the recording and not all such events are useful. However, UI elements such as drop-down menus can appear only on hover. You can manually add hover steps to user flows that depend on such elements.

To manually add a step:

  1. Open this demo page and start a new recording. Start a recording to capture a hover event.
  2. Hover over the element in the viewport. An action menu pops up. Hovering over the element.
  3. Pick an action from the menu and end the recording. The Recorder captures only the click event. Clicking an action and ending the recording.
  4. Try to replay the recording by clicking Replay. Replay. The replay fails after a timeout because the Recorder can't access the element in the menu. Replay fail.
  5. Click the Three-dot button. three-dot button next to the Click step and select Add step before. Adding a step before Click.
  6. Expand the new step. By default, it has the waitForElement type. Click the value next to type and select hover. Selecting hover.
  7. Next, set an appropriate selector for the new step. Click Select. Select, then click an area on the Hover over me! element that's outside the pop-up menu. The selector is set to #clickable. Setting the selector.
  8. Try replaying the recording again. With the added hover step, the Recorder successfully replays the flow. Replay success.

Remove steps

To remove an accidentally recorded step, select Remove step from the Three-dot button. three-dot menu next to the step.

Remove a step.

Configure steps

To configure a step:

  1. Specify its type: click, doubleClick, (input) change, keyUp, keyDown, scroll, close, navigate (to a page), waitForElement, or waitForExpression.

    Other properties depend on the type value.

  2. Specify the required properties below the type.

    Configuring a step.
  3. Click the corresponding buttons to add optional type-specific properties and specify them.

For a list of available properties, see Step properties.

To remove an optional property, click the Remove. Remove button next to it.

To add or remove an element to or from an array property, click the + or - buttons next to the element.

Step properties

Each step can have the following optional properties:

  • target—a URL for the Chrome DevTools Protocol (CDP) target, the default main keyword refers to the current page.
  • assertedEvents that currently can only be a single navigation event

Other common properties available for most of the step types are:

  • frame—an array of zero-based indexes that identify an iframe that can be nested. For example, you can identify the first (0) iframe inside a second (1) iframe of the main target as [1, 0].
  • timeout—a number of milliseconds to wait before executing a step. For more information, see Adjust timeouts for steps.
  • selectors—an array of selectors. For more information, see Understand selectors.

Type-specific properties are:

TypePropertyRequiredDescription
click, doubleClickoffsetX, offsetYCheck.Relative to the top-left of the element content box, in pixels
click, doubleClickbuttonPointer button: primary | auxiliary | second | back | forward
changevalueCheck.Final value
keyDown, keyUpkeyCheck.Key name
scrollx, yAbsolute scroll x and y positions in pixels, default 0
navigateurlCheck.Target URL
waitForElementoperator>= | == (default) | <=
waitForElementcountNumber of elements identified by a selector
waitForExpressionexpressionCheck.JavaScript expression that resolves to true

There are two properties that make the replay pause:

  • The waitForElement property makes the step wait for the presence (or absence) of a number of elements identified by a selector. For example, the following step waits for less than three elements to be on the page that match the selector .my-class.

      "type": "waitForElement",
    "selectors": [".my-class"],
    "operator": "<=",
    "count": 2,
  • The waitForExpression property makes the step wait for a JavaScript expression to resolve to true. For example, the following step pauses for two seconds and then resolves to true allowing the replay to continue.

       "type": "waitForExpression",
    "expression": "new Promise(resolve => setTimeout(() => resolve(true), 2000))",

Adjust timeouts for steps

In case your page has slow network requests or lengthy animations, the replay can fail on steps that exceed the default timeout of 5000 milliseconds.

To avoid this problem, you can adjust the default timeout for each step at once or set separate timeouts for specific steps. Timeouts on specific steps overwrite the default.

To adjust the default timeout for each step at once:

  1. Click on Replay settings to make the Timeout box editable.

    Replay settings.
  2. In the Timeout box, set the timeout value in milliseconds.

  3. Click Replay.Replay to see the adjusted default timeout in action.

To overwrite the default timeout on a specific step:

  1. Expand the step and click Add timeout.

    Add timeout.
  2. Click on the timeout: <value> and set the value in milliseconds.

    Set the timeout value.
  3. Click Replay.Replay to see the step with the timeout in action.

To remove a timeout overwrite on a step, click the DeleteDelete. button next to it.

Understand selectors

During recording, the Recorder automatically detects two types of selectors for most of the steps: ARIA and CSS.

For more information on ARIA selectors, see Syntactic vs. semantic selectors.

For simple webpages, id attributes and CSS class attributes are sufficient for the Recorder to detect the selectors. However, that might not always be the case, because:

  • Your webpages may use dynamic classes or ID's that change
  • Your selectors may break from development changes to CSS styles or JS behavior

Common test selectors

For example, the CSS class values might be auto-generated for applications developed with modern JavaScript frameworks (for example, React, Angular, Vue) and CSS frameworks.

Auto-generated CSS classes with randomized names.

In these cases, you can use data-* attributes to create more resilient tests. There are already some common data-* selectors that people use for automation. The Recorder supports them as well.

If you have the following common test selectors defined, the Recorder automatically detects and uses them first:

  • data-testid
  • data-test
  • data-qa
  • data-cy
  • data-test-id
  • data-qa-id
  • data-testing

For example, inspect the "Cappuccino" element on this demo page and see the test attributes:

Defined test selectors.

Record a click on "Cappuccino", expand the corresponding step in the recording, and check the detected selectors:

Detected common test selector.

Customize the recording's selector

You can customize the selector of a recording if the above doesn't work for you.

For example, this demo page uses the data-automate attribute as the selector. Start a new recording and enter the data-automate as the selector attribute.

Customize the recording's selector.

Fill in an email address and observe the selector value ([data-automate=email-address]).

The result of custom selector selection.

Selector priority

In addition to the ARIA selector, the Recorder looks for the best CSS selector it can find by the following attributes and in the following order:

  1. Your custom selector attribute if you specified it at the start of the recording.
  2. ARIA selector if found.
  3. The most common attributes used for testing:
    • data-testid
    • data-test
    • data-qa
    • data-cy
    • data-test-id
    • data-qa-id
    • data-testing
  4. ID attributes, for example, <div id="some_ID">.
  5. Regular CSS selectors.

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.