@puppeteer/replay

API | Contributing

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

Installation

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, like Cypress test script)

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);
await runner.run();

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);
    console.log('starting');
  }

  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);
    console.log('done');
  }
}

const runner = await createRunner(
  {
    title: 'Test recording',
    steps: [
      {
        type: 'navigate',
        url: 'https://wikipedia.org',
      },
    ],
  },
  new Extension(browser, page, 7000)
);

await runner.run();

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';

console.log(
  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);
    args[0].appendLine('console.log("starting");');
  }

  // 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) {
    args[0].appendLine('console.log("finished");');
    await super.afterAllSteps(...args);
  }
}

console.log(
  await stringify(
    {
      title: 'Test recording',
      steps: [
        {
          type: 'navigate',
          url: 'https://wikipedia.org',
        },
      ],
    },
    {
      extension: new Extension(),
      indentation: '	', // use tab to indent lines
    }
  )
);

Others

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.

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: