How to Automate User Flows with Chrome DevTools Recorder
Record, replay, debug, and export browser workflows with Chrome DevTools Recorder, then make them more dependable with stable selectors, waits, and assertions.
Chrome DevTools Recorder lets you capture interactions in a browser, replay them, edit and debug individual steps, and export a flow for reuse. To get a dependable flow, replay it early, replace fragile selectors where possible, add checks for important outcomes, and tune waits for the page. Recorder captures browser interactions; it does not guarantee that a flow will remain reliable as the site changes.
1. Open Chrome DevTools Recorder
- Open the page or app where you want to record a workflow.
- Open DevTools. On macOS, press Command+Shift+P. On Windows, Linux, or ChromeOS, press Control+Shift+P.
- Type
Recorder panel, choose Show Recorder panel, and press Enter.
You can also open it from DevTools using More options > More tools > Recorder panel. Recorder can capture, replay, edit, and debug flows, create performance profiles, and share or export recordings. See the Chrome DevTools Recorder guide.
2. Record a representative user flow
- In Recorder, start a new recording and give it a descriptive name.
- Perform the intended journey in the page: for example, open a navigation menu, search, choose a result, fill a form, and reach the confirmation state.
- Stop the recording when the meaningful outcome has appeared.
Record the shortest representative path that proves the user goal. Avoid incidental clicks or unrelated navigation; extra steps create more places for a flow to break. Use a test account and non-production data when the journey submits information or changes state.
Check the automatic starting steps
Recorder starts every recording with viewport and navigation steps. Navigation sets the URL and refreshes the page during replay. Keep it when each run should start from a fresh load; remove it for in-page automation that should use the current page without reloading.
3. Replay early and inspect failures
Replay as soon as you finish recording, before adding more steps. Recorder runs flows as quickly as it can by default, which can expose timing assumptions that were hidden during a manual session.
- Use a slower replay mode to see what happens around a failure.
- Use breakpoints or step-by-step execution to identify the first step that diverges.
- Inspect the page state and step parameters, then edit, remove, or add steps as needed.
The Recorder code view updates when you edit steps, but the code view itself is not editable. Make changes in the step list or export the flow if you need direct code-level customization.
4. Make the flow more dependable
Prefer selectors that reflect application intent
Recorder can detect common test attributes such as data-testid, data-test, data-qa, and data-cy. Prefer a stable test attribute agreed with the application team over a class or ID generated by styling or build tooling. Dynamic classes and IDs can change when the UI is redesigned, even when the user journey is unchanged. No selector is immune to application changes, so review flows when the page changes.
Add assertions for meaningful outcomes
For important transitions, add an assertion rather than assuming that a click succeeded. An assertion creates a configurable waitForElement step. It can check selectors, HTML attributes, JavaScript properties, visibility, and related values. If the condition is not met before the timeout, replay reports an error.
Assert the result that matters to the user, such as a confirmation heading becoming visible or a selected item appearing in a summary. Avoid checks tied to decorative details that can change without affecting the task.
Use waits that match the page
The documented default step timeout is 5,000 milliseconds. A slow request or long animation may need more time. Increase the replay timeout globally or override it on a step where the slower behavior is expected. Prefer waiting for a meaningful selector or state over adding a large fixed delay; a delay always costs that time, even when the page is ready sooner.
Handle hover-only menus explicitly
Recorder does not automatically capture hover events in some situations. If a menu appears only on hover, a recording may include a click on an item that is not present during replay. Add and configure a hover step with an appropriate selector, then replay the flow to confirm the menu opens before the next action.
5. Choose an export that fits the next step
| Export | Use it when | Can you import it back into Recorder? |
|---|---|---|
| JSON | You want readable flow data that can be edited, shared, and imported into Recorder again. | Yes |
| @puppeteer/replay | You want to retain JSON steps and replay them with the Puppeteer Replay library, including in a CI workflow. | The JSON flow remains the editable source. |
| Puppeteer script | You want generated JavaScript to customize directly, such as adding a loop. | No. It is generated code, not an importable Recorder flow. |
| Puppeteer for Firefox | You are exploring the documented WebDriver BiDi route for Chrome and Firefox. | Depends on the chosen workflow. |
| Puppeteer with Lighthouse analysis | You want the generated flow code to include Lighthouse analysis. | Depends on the chosen workflow. |
To export, open the flow’s Export menu and choose the format. To reuse JSON in Recorder, use its import option. Puppeteer Replay is an open-source library built on Puppeteer and can replay JSON files from the command line. The Chrome documentation also lists converters for Cypress, Nightwatch, and CodeceptJS, plus replay options involving TestCafe and Sauce Labs. Check present maintenance and compatibility before depending on any third-party converter or integration.
6. Troubleshoot common replay problems
| Symptom | Likely cause | What to try |
|---|---|---|
| A click step cannot find its target. | The selector is based on a changing class or ID, or the target has not appeared yet. | Use a stable test attribute where available and wait for the target selector before interacting. |
| The next step runs before a menu appears. | The menu opens on hover, which Recorder may not have captured automatically. | Add a hover step for the trigger, then replay one step at a time. |
| A step times out on a slow page. | The page or animation took longer than the default 5-second step timeout. | Increase the global replay timeout or set a longer timeout on that step. Use a state-based wait when possible. |
| The flow starts at the wrong page or reloads unexpectedly. | The initial navigation step resets the page on each replay. | Edit or remove that step if the flow should continue in the current page. |
| A recorded click works manually but fails during replay. | The page state, timing, or element visibility differs between recording and replay. | Slow playback, add a wait for the intended state, inspect the failing step, and add an assertion after the action. |
| Exported script changes are missing from Recorder. | A Puppeteer script is not the same as the importable JSON flow. | Keep JSON as the Recorder source, or maintain the generated script separately. Choose based on whether Recorder importability or direct code control matters more. |
7. Performance, reliability, and maintenance
- Replay speed: fast replay is useful for routine runs; slower modes and step-through execution help diagnose failures. A fixed delay can make a flow slower without making it more dependable.
- Reliability: selectors, waits, and assertions reduce avoidable failures, but site changes can still require edits. Keep a clear owner for updating flows alongside UI changes.
- CI use: export JSON for Puppeteer Replay when you want the flow steps to remain portable, or use generated Puppeteer JavaScript when you need code-level control. Confirm that the runner has the browser, credentials, network access, and test data the journey needs.
- Cost: Recorder is a Chrome DevTools capability. Exported libraries, CI runners, and third-party extensions may have their own setup or costs; check their current terms before adopting them.
Or skip the browser setup
If your goal is a clean screenshot of a page rather than replaying an interactive journey, ScreenshotNeo can return one with a single GET request. Its API accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It is a screenshot API, not a browser-flow recorder.
Install Python’s requests package, set your API key, and save this as a Python file to capture a page:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as image:
image.write(r.content)Equivalent cURL and Node.js calls:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpconst q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);See the ScreenshotNeo API documentation for parameters and configuration. It supports full-page and element captures, device and viewport settings, image formats, PDF options, custom CSS and JavaScript, waits, request blocking, headers and cookies, caching, async jobs, bulk capture, and more. 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Can I edit a flow after recording?
Yes. Edit, add, or remove steps in Recorder. The code view reflects those changes but is not a code editor.
Which export should I keep as the source of truth?
Keep JSON if you need to import and continue editing the flow in Recorder. Use a generated Puppeteer script when direct JavaScript customization is the priority.
Does Recorder guarantee a flow will keep working?
No. Replays can fail when the page, selectors, timing, or data changes. Early replay, stable selectors, and assertions make failures easier to find and repair.
Can Recorder capture an entire multi-page website?
Recorder captures a specific interaction flow. Record the particular journey and starting conditions you need to repeat.
