In this article, we’ll be diving into arguably one of Puppeteer’s most useful features - creating session recordings using the Replay library. The Puppeteer Replay library provides a high-level API to control Chrome, allowing developers to automate and test modern web experiences efficiently.

Why create session recordings?

Creating session recordings can be quite beneficial for developers and everyone involved in the process. 

Visualizing test execution

Recording your Puppeteer scripts in action gives you a clear, step-by-step visual of how they interact with web pages. This is extremely helpful for debugging and understanding script functionality. Instead of just reading code and comments, you can see the actual interactions, making it easier to identify and resolve issues.

Sharing test results

After recording your test, you can easily share it with your team or project stakeholders. This is especially useful for those who may not be familiar with Puppeteer. They can watch the recording to understand how the automation works and spot any problems.

Prerequisites

The main players responsible for the session recording capabilities are the Puppeteer Replay library and the Chrome Devtools Recorder. It's true that you could use the Puppeteer screen recorder for video recording, but using the Developer tools recorder from the devtools chrome extension gives you a more comprehensive view of the tasks carried out during the session.

Although the Chrome dev tools recorder records your session, you don't have to download it. It’s readily available in your Google Chrome Browser Devtools. 

Assuming that you’ve already installed node.js and npm, you should start by installing the replay library. You can do so by following these instructions.

1. Open your terminal and navigate to your project directory where you want to use Puppeteer Replay.
2. Run this command - 

npm install @puppeteer/replay

This should download and install the Puppeteer Replay library and its associated dependencies. 

How to create session recordings in Puppeteer?

Once you’ve got the prerequisites down, it's time to start recording, so let’s open up the Chrome tools.

Step 1: Open the console

Start by opening Chrome Devtools by using the shortcut Ctrl + Shift + J

Step 2: Navigate to the recorder

1. Once the console is open you should then be able to navigate to the recorder by clicking on the three dots “⁝” icon on the console and clicking on “Run command”, or just use the shortcut “Ctrl + Shift + P”
2. Type “Show recorder” in the text box and click on the result.

Step 3: Record and Save

1. Click on “Create a new recording” and give your recording a name by filling in the text box that pops up. Once you click enter, click on the “Start a new recording” button at the bottom to start recording. This will record browser actions like our interactions with each page object in point form.
2. Once you’re done recording the session, you can end it by clicking on the “End recording” at the bottom. This will show you the actions taken step by step and view the associated code for it as well. Then you can download the recording by clicking on the download icon, and selecting the format as a JSON, which will generate a JSON file with captured interactions. The devtools recorder does allow you to generate puppeteer scripts from the recordings, but using a JSON format gives you a higher level of control.

Step 4: Replay

There are 2 main ways in which you can replay a Recording using Puppeteer Replay.

1. Using the Command Line Interface and npx

Open your terminal and navigate to your project directory. Then you should run the following command. Make sure to replace “recording.json” with the actual name of your recording

npx @puppeteer/replay recording.json

You could also launch it in headless mode, without a Graphical User Interface. 

npx @puppeteer/replay recording.json --headless

Or collectively replay all recordings in a folder. Just make sure to replace the “all-recordings” with an actual file path.

npx @puppeteer/replay all-recordings

2. Using the replay library

This method gives you programmatic control over the replay process because it allows you to integrate with other additional tools, add assertions within your code using the library, and modify them before replaying. Here’s a snippet showing you how to do it. Make sure to replace “path/to/your/recording.har” with the path of your file.

const puppeteer = require('puppeteer');
const replay = require('puppeteer-replay');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  const recordingFile = 'path/to/your/recording.har';

  await replay.replay(page, recordingFile);

//the await browser function waits for the browser to close
  await browser.close();
})();

This code launches a headless browser with a new page and uses the puppeteer-replay library to replay the user interactions recorded during the session. 

Streamlining tips

In order to make the most out of your replays, you can follow some best practices. 

Customize your replay - As we mentioned, Puppeteer’s Replay library allows you to customize your replay by filtering specific actions, adjusting timeouts, or adding wait conditions to tailor the replay to your testing requirements. Here’s a code block example showing you how.

const replay = require('@puppeteer/replay');

const filteredActions = replay.filterActions(recording, action => action.name === 'click' || action.name === 'type');

await replay.replay(page, filteredActions, { timeout: 10000 }); 

The above code shows you how to filter actions to include only the login steps. It also replays the filtered session with a longer timeout for a specific step using “await replay.replay”, with a timeout of 10 seconds.

Conditional logic - You could also incorporate conditional logic into your replay script to handle situations with different user inputs or application behaviors. This makes the replay more adaptable to varying scenarios.

const isLoggedIn = await page.evaluate(() => document.querySelector('#logoutButton') !== null);

if (isLoggedIn) {
  // Perform actions specific to a logged-in user
} else {
  // Perform actions for a non-logged-in user
}

Integrated testing - Since Replay allows integration with other tools, you can make use of it by integrating Puppeteer Replay with your testing framework like a front-end testing tool. Popular frameworks like Jest or Mocha work well with Puppeteer. Here’s a snippet showing you how to integrate Jest.

test('Login and navigate to dashboard', async () => {
    const browser = await puppeteer.launch();
    const page = await browser.newPage();
     const recording = require('./login_recording.json');
 
    await replay.replay(page, recording);
 
    await expect(page.url()).toContain('/dashboard');
 
    await browser.close();
  });

This code loads the login recording, replays the session, and adds assertions to verify dashboard navigation. 

Additional resources

In addition to this article, you can also use resources like the official GitHub repository of Puppeteer Replay for more programmatic approaches. 

Conclusion

Replay in Puppeteer allows you to replay session recordings made via Chrome Devtools. Replaying your session recordings can be quite beneficial for development teams in many ways like visualizing test executions, sharing your test recording with results, and as documentation to train new developers. While this can be done in a few methods, by using the Replay library and following our streamlining tips, you can further configure your replay to meet your needs.