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:
- A Browserless account and API key
- Node.js installed on your system (for code examples)
- The required npm packages:
npm install puppeteer-core
Recording a Session
- Connect to Browserless with Replay Enabled- Connect to Browserless and enable session replay recording by adding the - replay=truequery parameter to your connection URL.- Puppeteer
- Playwright
 - 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`,
 });- 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'
 );
- 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
- Playwright
 - 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);- 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);
- Stop Recording and Clean Up- Create a CDP session, stop the session recording, and close the browser connection to finalize the recording. - Puppeteer
- Playwright
 - const cdp = await page.createCDPSession();
 // Stop the recording
 await cdp.send("Browserless.stopSessionRecording");
 await browser.close();- const cdpSession = await context.newCDPSession(page);
 // Stop the recording
 await cdpSession.send("Browserless.stopSessionRecording");
 await browser.close();
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: