Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit

Bumps [puppeteer-core]( from 19.6.2 to 19.6.3.
- [Release notes](
- [Changelog](
- [Commits](puppeteer/puppeteer@puppeteer-core-v19.6.2...puppeteer-core-v19.6.3)

- dependency-name: puppeteer-core
  dependency-type: direct:development
  update-type: version-update:semver-patch

Signed-off-by: dependabot[bot] <>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]>

Git stats


Failed to load latest commit information.
Latest commit message
Commit time
February 1, 2023 08:54
February 1, 2023 09:47
February 2, 2022 09:20
February 1, 2022 10:04


Build status npm puppeteer package

API | Contributing

Puppeteer Replay is a library that provides an API to replay and stringify recordings created using Chrome DevTools Recorder


npm install @puppeteer/replay --save

If you want to replay recordings using Puppeteer, install Puppeteer as well:

npm install puppeteer --save

Getting started with Puppeteer Replay

You can use Puppeteer Replay to:

  1. Replay recording. Replay recording with CLI or using the replay lib API.
  2. Customize replay. Customize how a recording is run. For example, capture screenshots after each step or integrate with 3rd party libraries.
  3. Transform recoding. Customize how a recording is stringified. For example, transform the recording into another format.

Also, you can use third-party integrations that build on top of @puppeteer/replay, which includes:

Transform JSON user flows to custom scripts:

Replay JSON user flows:

1. Replay recording

Download this example recording and save it as recording.json.

Using CLI + npx:

npx @puppeteer/replay recording.json

Using CLI + package.json:

In your package.json add a new script to invoke the replay command:

  "scripts": {
    "replay": "replay recording.json"

You can also give folder name as a parameter to run all the files in a folder.

Using CLI + npx:

npx @puppeteer/replay all-recordings # runs all recordings in the "all-recordings" folder.

Using CLI + package.json:

  "scripts": {
    "replay": "replay all-recordings"

Set the PUPPETEER_HEADLESS environment variable or --headless CLI flag to control whether the browser is start in a headful or headless mode. For example,

PUPPETEER_HEADLESS=true npx @puppeteer/replay recording.json # runs in headless mode, the default mode.
PUPPETEER_HEADLESS=false npx @puppeteer/replay recording.json # runs in headful mode.
PUPPETEER_HEADLESS=chrome npx @puppeteer/replay recording.json # runs in the new experimental headless mode.

Use the --extension CLI flag to provide a custom replay extension for running the recording. For example,

npx @puppeteer/replay --extension examples/cli-extension/extension.js recording.json

Run npx @puppeteer/replay --help to see all CLI options.

Using the replay lib API:

import { createRunner, parse } from '@puppeteer/replay';
import fs from 'fs';

// Read recording for a file.
const recordingText = fs.readFileSync('./recording.json', 'utf8');
// Validate & parse the file.
const recording = parse(JSON.parse(recordingText));
// Create a runner and execute the script.
const runner = await createRunner(recording);

2. Customize replay

The library offers a way to customize how a recording is run. You can extend the PuppeteerRunnerExtension class as shown in the example below.

Full example of the PuppeteerRunnerExtension: link

import { createRunner, PuppeteerRunnerExtension } from '@puppeteer/replay';
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,

const page = await browser.newPage();

class Extension extends PuppeteerRunnerExtension {
  async beforeAllSteps(flow) {
    await super.beforeAllSteps(flow);

  async beforeEachStep(step, flow) {
    await super.beforeEachStep(step, flow);
    console.log('before', step);

  async afterEachStep(step, flow) {
    await super.afterEachStep(step, flow);
    console.log('after', step);

  async afterAllSteps(flow) {
    await super.afterAllSteps(flow);

const runner = await createRunner(
    title: 'Test recording',
    steps: [
        type: 'navigate',
        url: '',
  new Extension(browser, page, 7000)


await browser.close();

3. Transform recording

You can customize how a recording is stringified and use it to transform the recording format.

Stringify a recording as a Puppeteer script

import { stringify } from '@puppeteer/replay';

  await stringify({
    title: 'Test recording',
    steps: [],

Customize how a recording is stringified

You can customize how a recording is stringified by extending the PuppeteerStringifyExtension class as shown in the example below.

Full example of PuppeteerStringifyExtension : link

import { stringify, PuppeteerStringifyExtension } from '@puppeteer/replay';

class Extension extends PuppeteerStringifyExtension {
  // beforeAllSteps?(out: LineWriter, flow: UserFlow): Promise<void>;
  async beforeAllSteps(...args) {
    await super.beforeAllSteps(...args);

  // beforeEachStep?(out: LineWriter, step: Step, flow: UserFlow): Promise<void>;
  async beforeEachStep(...args) {
    await super.beforeEachStep(...args);
    const [out, step] = args;
    out.appendLine(`console.log("about to execute step ${step.type}")`);

  // afterEachStep?(out: LineWriter, step: Step, flow: UserFlow): Promise<void>;
  async afterEachStep(...args) {
    const [out, step] = args;
    out.appendLine(`console.log("finished step ${step.type}")`);
    await super.afterEachStep(...args);

  // afterAllSteps?(out: LineWriter, flow: UserFlow): Promise<void>;
  async afterAllSteps(...args) {
    await super.afterAllSteps(...args);

  await stringify(
      title: 'Test recording',
      steps: [
          type: 'navigate',
          url: '',
      extension: new Extension(),
      indentation: '	', // use tab to indent lines


Test your extensions using the replay lib

The replay lib offers a canonical recording and a test page that allows to verify that your extension produces all expected side effects on a page.

The test command supports both stringify and runner extensions. The stringify extension will be tested by running the stringified script using node. Run the test using the following command.

npx -p @puppeteer/replay replay-extension-test --ext path-to-your-extension-js

Create a Chrome extension for Recorder (Available from Chrome 104 onwards)

You can create a Chrome extension for Recorder. Refer to the Chrome Extensions documentation for more details on how to extend DevTools.

For example, here are some of the third party extensions:

This feature only available from Chrome 104 onwards. Check your current Chrome version with chrome://version. Consider installing Chrome Canary to try out cutting-edge features in Chrome.

This repository contains an example extension. Once installed, the Recorder will have a new export option Export as a Custom JSON script in the export dropdown.

To load the example into Chrome DevTools. Follow these steps:

  1. Download the chrome-extension folder.
  2. Load the folder as unpacked extension in Chrome.
  3. Open a recording in the Recorder.
  4. Click on export. Now you can see a new Export as a Custom JSON script option in the export menu.

Click and watch the video demo below:

Demo video that shows how to extend export options in Recorder panel by adding a Chrome extension