Session Replay

The Session Replay feature lets you record browser sessions and later replay them for debugging and analysis.

This feature is particularly useful for:

• Debugging complex user workflows and interactions
• Creating visual documentation of browser automation processes
• Troubleshooting issues with recorded evidence

Prerequisites

Before using Session Replay, make sure you have:

1. A Browserless account and API key
2. Node.js installed on your system (for code examples)
3. The required npm packages:

   npm install puppeteer-core

Recording a Session

1. Connect to Browserless with Replay Enabled

   Connect to Browserless and enable session replay recording by adding the replay=true query parameter to your connection URL.

   Puppeteer

   import puppeteer from 'puppeteer-core';
   
   const browser = await puppeteer.connect({
     browserWSEndpoint: `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&timeout=300000&headless=false&replay=true`,
   });

   Playwright

   import { chromium } from 'playwright-core';
   
   const browser = await chromium.connectOverCDP(
     'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&timeout=300000&headless=false&replay=true'
   );

2. Perform Actions to Record

   Create a page, navigate to your target website, and perform the actions you want to record. The recording will capture all interactions on this page.

   Puppeteer

   const page = await browser.newPage();
   await page.goto("https://www.example.com", { waitUntil: "networkidle0" });
   
   const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
   
   // Example: Random mouse movements for demonstration
   const randomMouseMovements = async (page, moves = 20) => {
     const viewport = page.viewport() || { width: 1280, height: 720 };
     for (let i = 0; i < moves; i++) {
       const x = Math.floor(Math.random() * viewport.width);
       const y = Math.floor(Math.random() * viewport.height);
   
       await page.mouse.move(x, y, {
         steps: 5 + Math.floor(Math.random() * 10),
       });
       await sleep(100 + Math.random() * 300);
     }
   };
   
   await randomMouseMovements(page, 2);
   await sleep(6000);

   Playwright

   const [context] = await browser.contexts();
   const page = await context.newPage();
   await page.goto("https://www.example.com", { waitUntil: "networkidle" });
   
   const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
   
   // Example: Random mouse movements for demonstration
   const randomMouseMovements = async (page, moves = 20) => {
     const viewport = page.viewportSize() || { width: 1280, height: 720 };
     for (let i = 0; i < moves; i++) {
       const x = Math.floor(Math.random() * viewport.width);
       const y = Math.floor(Math.random() * viewport.height);
   
       await page.mouse.move(x, y);
       await sleep(100 + Math.random() * 300);
     }
   };
   
   await randomMouseMovements(page, 2);
   await sleep(6000);

3. Stop Recording and Clean Up

   Create a CDP session, stop the session recording, and close the browser connection to finalize the recording.

   Puppeteer

   const cdp = await page.createCDPSession();
   
   // Stop the recording
   await cdp.send("Browserless.stopSessionRecording");
   await browser.close();

   Playwright

   const cdpSession = await context.newCDPSession(page);
   
   // Stop the recording
   await cdpSession.send("Browserless.stopSessionRecording");
   await browser.close();

BQL Users

For BrowserQL-specific Session Replay documentation, see Session Replay with BQL.

Next Steps

Ready to explore more recording capabilities? Consider these alternatives for different use cases:

Screencast API

See how to generate a video file from your code.

Recording with LiveURL

Capture complete browser sessions as WebM video files while enabling human intervention when needed