How to Record Puppeteer Scripts
Record browser actions in Chrome DevTools Recorder, export them as Puppeteer code, and learn when to use JSON, MP4 recording, or performance traces.
To record browser actions and turn them into a Puppeteer script, use Chrome DevTools Recorder: record a flow, then choose Export > Puppeteer. The result is editable JavaScript you can customize and run with Puppeteer. If you need a flow you can edit and import back into Recorder, export JSON instead; exported Puppeteer JavaScript cannot be imported back.
“Record a Puppeteer script” can also mean saving a video of a page or capturing a performance trace. Those are separate workflows: Puppeteer’s experimental page.record() API produces an MP4 stream, while tracing creates diagnostic performance data.
Record actions and export Puppeteer code
- Open the page you want to automate in Chrome.
- Open Chrome DevTools. Open the Command menu with Command+Shift+P on macOS or Control+Shift+P on Windows, Linux, or ChromeOS. Search for “Recorder panel” and select it. You can also use More options > More tools > Recorder panel.
- In Recorder, start a new recording and perform the user flow: click controls, fill fields, navigate, and take the actions your automation needs to reproduce.
- Stop the recording, review the captured steps, and edit the flow if needed.
- Use Export and select Puppeteer. Save the generated JavaScript.
- Review the generated code, adapt it to your project, then run it with Puppeteer.
Recorder tracks a flow that can be replayed, edited, and exported. The code shown by the export reflects the recorded steps; change the flow in Recorder if you want its displayed export to update.
What the Recorder export gives you
The exported JavaScript is a starting point for automation, not a guarantee that the flow will work unchanged in every environment. Review selectors, navigation assumptions, timing, authentication, and any data that changes between runs. Keep credentials out of committed scripts and supply them through your project’s normal secret configuration.
Use this export when the desired result is Puppeteer JavaScript you can customize and run. It cannot be imported back into Recorder. For a flow that can make the round trip back into Recorder, choose JSON.
Choose the right recording format
| Goal | Choose | What to know |
|---|---|---|
| Get editable browser automation code | Puppeteer | Exports JavaScript to customize and replay with Puppeteer. It cannot be re-imported into Recorder. |
| Keep an editable, re-importable flow | JSON | Recorder’s human-readable flow format can be edited, imported into Recorder, or replayed with tooling. |
| Replay a Recorder-created flow through the replay library | @puppeteer/replay |
The export remains a JSON object. Puppeteer Replay provides APIs to replay and stringify Recorder recordings. |
| Run a Puppeteer export associated with Firefox | Puppeteer for Firefox | Chrome documents a separate format associated with WebDriver BiDi. Check support for the Puppeteer version and browsers in your target environment. |
| Include Lighthouse analysis | Puppeteer with Lighthouse analysis | Choose this Recorder export when the flow should include Lighthouse analysis code. |
| Save page activity as a video | page.record() |
A separate experimental Puppeteer API that records an MP4 stream; it does not generate a script from clicks. |
| Investigate performance | Puppeteer tracing | Creates a diagnostic trace file for Chrome DevTools or a timeline viewer, not a user-flow script or MP4. Only one trace can be active per browser. |
Run and maintain the generated script
Recorder produces a Puppeteer script, but the exact generated code depends on the recorded flow and export. Use the saved export as your runnable source file, then make the following checks before relying on it:
- Confirm the runtime: install Puppeteer in the project and run the script with the Node.js version and browser setup used by your automation environment.
- Check selectors: ensure each recorded target still exists and uniquely identifies the intended control. Replace brittle selectors if the page changes often.
- Check navigation and waits: verify the script waits for the page state your next action needs, especially after navigation, form submission, or content loaded asynchronously.
- Make inputs repeatable: use known test data and a clean starting state. Avoid depending on values left over from a previous run.
- Handle authentication safely: use an approved test account and load secrets from environment configuration or a secret store, not source code.
- Run it where it will execute: browser versions, headless settings, network access, and operating-system dependencies can differ between a developer laptop and CI.
For a reusable flow that non-code users can re-import and adjust in Recorder, keep the JSON recording alongside the script where appropriate. Treat the exported JavaScript as the executable artifact and JSON as the flow representation.
Record a video with Puppeteer instead
If “record” means save what the page displays as a video, Puppeteer 25.12.0 documents the experimental page.record() API. It returns a recording whose output is an MP4 stream; call stop() to finish. This captures page video, not the sequence of actions as automation code.
// Illustrative API shape from the Puppeteer Page.record() workflow.
// Check the API reference and your installed Puppeteer/Chrome versions
// before adopting this experimental API.
const recording = await page.record();
// Perform or wait for the page activity to capture.
const mp4Stream = await recording.stop();
// Consume or save the returned MP4 stream using the API shape
// documented for the Puppeteer version installed in your project.The API reference labels record() experimental, so verify compatibility in the version you deploy. Puppeteer’s Page API marks screencast() obsolete and directs users toward Page.record(); that reference says screencast requires Chrome 153 or newer and ffmpeg. Check current documentation before relying on either API.
Capture a performance trace instead
For performance diagnosis, use Puppeteer tracing. It writes a trace file that can be opened in Chrome DevTools or a timeline viewer. A trace is diagnostic event data; it is not a Puppeteer script generated from interactions and it is not an MP4 page recording. Only one trace can be active per browser.
Choose tracing when you need to inspect browser activity and performance. Choose Recorder when you need a repeatable interaction flow, and page.record() when you need a video artifact.
Or skip the browser setup
If your goal is a screenshot of a page rather than a recorded Puppeteer interaction flow, ScreenshotNeo can return an image or PDF with one GET request. See the ScreenshotNeo API documentation for the available parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month, no card.
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| Recorder panel does not open | The Command menu search did not find the panel, or the menu path differs in the current Chrome UI. | Search for “Recorder panel” from the DevTools Command menu. Alternatively, open DevTools’ More options menu and look under More tools. Chrome’s Recorder UI can change, so consult the current Chrome DevTools Recorder guide if labels differ. |
| Exported Puppeteer option is missing | You may be looking at a different Recorder export menu or a changed Chrome UI. | Open the recording’s Export control and inspect the available formats. Use JSON if you need a portable flow and Puppeteer JavaScript is not available in that environment. |
| The exported script cannot be imported into Recorder | Puppeteer JavaScript is an execution export, not the round-trip flow format. | Export JSON from Recorder when you need to edit or re-import the flow. |
| Replay fails on a selector | The page markup may have changed, the selector may match more than one element, or the target may not yet be available. | Inspect the failing step in Recorder, update the flow to target the intended element, and regenerate the export. Ensure the page reaches the required state before the interaction. |
| A step runs before the page is ready | Navigation or asynchronous content may take longer than the recorded run. | Adjust the flow or generated script to wait for the required page state rather than relying on the original recording’s timing. |
| The flow works locally but fails in automation | The execution environment may differ in browser version, headless configuration, credentials, data, or network access. | Reproduce the target environment, provide test data and secrets through its configuration, and verify browser compatibility. |
page.record() is unavailable or fails |
The API is experimental and support depends on Puppeteer and browser versions. | Check the Page.record() reference for the installed version and its compatibility requirements. Do not assume the older screencast API is interchangeable. |
| A trace cannot start | A trace may already be active for the browser. | Stop the active trace before starting another; Puppeteer permits only one active trace per browser. |
Performance, reliability, and cost
- Performance: the Recorder-generated script runs browser actions, so runtime depends on the page, network, waits, and work performed by the flow. Keep the recording focused on the actions needed for the task.
- Reliability: a recorded flow reflects one observed run. Pages can change, and asynchronous content or different environments can make later runs behave differently. Review selectors and readiness conditions and use controlled test data.
- Cost: Chrome DevTools Recorder and Puppeteer are software workflows; the cited documentation does not establish a usage price for running your automation. Your deployment environment may have its own infrastructure costs.
- Version compatibility: Recorder’s interface and export choices may change. The
page.record()API is documented as experimental; verify current Puppeteer and Chrome support before building a dependency on it.
FAQ
Can I edit the Puppeteer code while recording?
Edit the flow in Recorder and regenerate or refresh the displayed export to reflect its steps. The exported JavaScript itself is the code artifact to customize for execution.
Can I use the recording with Firefox?
Recorder documents a Puppeteer for Firefox export associated with WebDriver BiDi. Confirm current support for the Puppeteer version and browser combination you plan to run.
Does a performance trace record a video?
No. A trace is diagnostic performance data. Use page.record() for the separate experimental MP4 recording workflow.
Which format should I keep in source control?
Keep the artifact your team needs to maintain: Puppeteer JavaScript for executable automation, JSON for a flow that can be re-imported into Recorder, or both when both workflows matter. Avoid storing credentials in either file.
