{"id":13588573,"url":"https://github.com/puppeteer/replay","last_synced_at":"2025-05-13T21:04:42.551Z","repository":{"id":36950344,"uuid":"454321538","full_name":"puppeteer/replay","owner":"puppeteer","description":"Library that provides an API to replay and stringify recordings created using Chrome DevTools Recorder","archived":false,"fork":false,"pushed_at":"2025-04-27T01:19:40.000Z","size":1871,"stargazers_count":1146,"open_issues_count":18,"forks_count":391,"subscribers_count":151,"default_branch":"main","last_synced_at":"2025-04-28T12:14:46.878Z","etag":null,"topics":["automation","devtools","javascript","puppeteer"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppeteer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-01T09:08:54.000Z","updated_at":"2025-04-28T03:36:29.000Z","dependencies_parsed_at":"2024-01-05T14:29:34.041Z","dependency_job_id":"bfee49d5-5b5c-41ca-a7cf-6c0f0e710fb0","html_url":"https://github.com/puppeteer/replay","commit_stats":{"total_commits":537,"total_committers":19,"mean_commits":"28.263157894736842","dds":0.4878957169459963,"last_synced_commit":"0fbc66c619cc2edcda309e73be89b1a39d97bb15"},"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppeteer%2Freplay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppeteer%2Freplay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppeteer%2Freplay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppeteer%2Freplay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppeteer","download_url":"https://codeload.github.com/puppeteer/replay/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311332,"owners_count":21569009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","devtools","javascript","puppeteer"],"created_at":"2024-08-01T15:06:47.813Z","updated_at":"2025-04-28T12:14:55.500Z","avatar_url":"https://github.com/puppeteer.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","automation"],"sub_categories":[],"readme":"# @puppeteer/replay\n\n\u003c!-- [START badges] --\u003e\n\n[![Build status](https://github.com/puppeteer/replay/workflows/run-checks/badge.svg)](https://github.com/puppeteer/replay/actions?query=workflow%3Arun-checks) [![npm puppeteer package](https://img.shields.io/npm/v/@puppeteer/replay.svg)](https://npmjs.org/package/@puppeteer/replay)\n\n\u003c!-- [END badges] --\u003e\n\n###### [API](https://github.com/puppeteer/replay/blob/main/docs/api) | [Contributing](https://github.com/puppeteer/replay/blob/main/docs/contributing.md)\n\n\u003e Puppeteer Replay is a library that provides an API to replay and stringify recordings created using [Chrome DevTools Recorder](https://developer.chrome.com/docs/devtools/recorder/)\n\n## Installation\n\n```\nnpm install @puppeteer/replay --save\n```\n\nIf you want to replay recordings using Puppeteer, install Puppeteer as well:\n\n```\nnpm install puppeteer --save\n```\n\n## Getting started with Puppeteer Replay\n\nYou can use Puppeteer Replay to:\n\n1. **Replay recording**. Replay recording with CLI or using [the replay lib API](/examples/replay-from-file-using-puppeteer/main.js).\n2. **Customize replay**. Customize how a recording is run. For example, capture screenshots after each step or integrate with 3rd party libraries.\n3. **Transform recording**. Customize how a recording is stringified. For example, transform the recording into another format.\n\nAlso, you can use third-party integrations that build on top of `@puppeteer/replay`, which includes:\n\nTransform JSON user flows to custom scripts:\n\n- [Cypress Chrome Recorder](https://github.com/cypress-io/cypress-chrome-recorder). You can use it to convert user flow JSON files to Cypress test scripts. Watch this [demo](https://youtu.be/4qYs2bMz4GI) to see it in action.\n- [Nightwatch Chrome Recorder](https://github.com/nightwatchjs/nightwatch-chrome-recorder). You can use it to convert user flow JSON files to Nightwatch test scripts.\n- [WebdriverIO Chrome Recorder](https://github.com/webdriverio/chrome-recorder). You can use it to convert user flow JSON files to WebdriverIO test scripts.\n\nReplay JSON user flows:\n\n- [Replay with TestCafe](https://testcafe.io/documentation/403998/guides/experimental-capabilities/chrome-replay-support). You can use TestCafe to replay user flow JSON files and generate test reports for these recordings.\n- [Replay with Sauce Labs](https://saucelabs.com/blog/how-to-create-test-scripts-using-chrome-devtools). You can replay the JSON files on [Sauce Labs](https://saucelabs.com/) using [saucectl](https://github.com/saucelabs/saucectl-replay-example).\n\n## 1. Replay recording\n\nDownload this [example recording](https://storage.googleapis.com/web-dev-uploads/file/dPDCek3EhZgLQPGtEG3y0fTn4v82/vzQbv2rUfTz2DEmx06Gv.json) and save it as `recording.json`.\n\nUsing CLI + npx:\n\n```\nnpx @puppeteer/replay recording.json\n```\n\nUsing CLI + package.json:\n\nIn your `package.json` add a new script to invoke the `replay` command:\n\n```json\n{\n  \"scripts\": {\n    \"replay\": \"replay recording.json\"\n  }\n}\n```\n\nYou can also give folder name as a parameter to run all the files in a folder.\n\nUsing CLI + npx:\n\n```bash\nnpx @puppeteer/replay all-recordings # runs all recordings in the \"all-recordings\" folder.\n```\n\nUsing CLI + package.json:\n\n```json\n{\n  \"scripts\": {\n    \"replay\": \"replay all-recordings\"\n  }\n}\n```\n\nSet the `PUPPETEER_HEADLESS` environment variable or `--headless` CLI flag to control whether the browser is started in a headful or headless mode. For example,\n\n```\nPUPPETEER_HEADLESS=true npx @puppeteer/replay recording.json # runs in headless mode, the default mode.\nPUPPETEER_HEADLESS=false npx @puppeteer/replay recording.json # runs in headful mode.\nPUPPETEER_HEADLESS=chrome npx @puppeteer/replay recording.json # runs in the new experimental headless mode.\n```\n\nUse the `--extension` CLI flag to provide a [custom replay extension](https://github.com/puppeteer/replay#2-customize-replay) for running the recording. For [example](https://github.com/puppeteer/replay/blob/main/examples/cli-extension/extension.js),\n\n```sh\nnpx @puppeteer/replay --extension examples/cli-extension/extension.js recording.json\n```\n\nRun `npx @puppeteer/replay --help` to see all CLI options.\n\nUsing [the replay lib API](/examples/replay-from-file-using-puppeteer/main.js):\n\n```js\nimport { createRunner, parse } from '@puppeteer/replay';\nimport fs from 'fs';\n\n// Read recording for a file.\nconst recordingText = fs.readFileSync('./recording.json', 'utf8');\n// Validate \u0026 parse the file.\nconst recording = parse(JSON.parse(recordingText));\n// Create a runner and execute the script.\nconst runner = await createRunner(recording);\nawait runner.run();\n```\n\n## 2. Customize replay\n\nThe library offers a way to customize how a recording is run. You can extend\nthe `PuppeteerRunnerExtension` class as shown in the example below.\n\nFull example of the `PuppeteerRunnerExtension`: [link](/examples/extend-runner/main.js)\n\n```js\nimport { createRunner, PuppeteerRunnerExtension } from '@puppeteer/replay';\nimport puppeteer from 'puppeteer';\n\nconst browser = await puppeteer.launch({\n  headless: true,\n});\n\nconst page = await browser.newPage();\n\nclass Extension extends PuppeteerRunnerExtension {\n  async beforeAllSteps(flow) {\n    await super.beforeAllSteps(flow);\n    console.log('starting');\n  }\n\n  async beforeEachStep(step, flow) {\n    await super.beforeEachStep(step, flow);\n    console.log('before', step);\n  }\n\n  async afterEachStep(step, flow) {\n    await super.afterEachStep(step, flow);\n    console.log('after', step);\n  }\n\n  async afterAllSteps(flow) {\n    await super.afterAllSteps(flow);\n    console.log('done');\n  }\n}\n\nconst runner = await createRunner(\n  {\n    title: 'Test recording',\n    steps: [\n      {\n        type: 'navigate',\n        url: 'https://wikipedia.org',\n      },\n    ],\n  },\n  new Extension(browser, page, 7000)\n);\n\nawait runner.run();\n\nawait browser.close();\n```\n\n## 3. Transform recording\n\nYou can customize how a recording is stringified and use it to transform the recording format.\n\n### Stringify a recording as a Puppeteer script\n\n```js\nimport { stringify } from '@puppeteer/replay';\n\nconsole.log(\n  await stringify({\n    title: 'Test recording',\n    steps: [],\n  })\n);\n```\n\n### Customize how a recording is stringified\n\nYou can customize how a recording is stringified by extending the `PuppeteerStringifyExtension` class as shown in the example below.\n\nFull example of `PuppeteerStringifyExtension` : [link](/examples/extend-stringify/main.js)\n\n```js\nimport { stringify, PuppeteerStringifyExtension } from '@puppeteer/replay';\n\nclass Extension extends PuppeteerStringifyExtension {\n  // beforeAllSteps?(out: LineWriter, flow: UserFlow): Promise\u003cvoid\u003e;\n  async beforeAllSteps(...args) {\n    await super.beforeAllSteps(...args);\n    args[0].appendLine('console.log(\"starting\");');\n  }\n\n  // beforeEachStep?(out: LineWriter, step: Step, flow: UserFlow): Promise\u003cvoid\u003e;\n  async beforeEachStep(...args) {\n    await super.beforeEachStep(...args);\n    const [out, step] = args;\n    out.appendLine(`console.log(\"about to execute step ${step.type}\")`);\n  }\n\n  // afterEachStep?(out: LineWriter, step: Step, flow: UserFlow): Promise\u003cvoid\u003e;\n  async afterEachStep(...args) {\n    const [out, step] = args;\n    out.appendLine(`console.log(\"finished step ${step.type}\")`);\n    await super.afterEachStep(...args);\n  }\n\n  // afterAllSteps?(out: LineWriter, flow: UserFlow): Promise\u003cvoid\u003e;\n  async afterAllSteps(...args) {\n    args[0].appendLine('console.log(\"finished\");');\n    await super.afterAllSteps(...args);\n  }\n}\n\nconsole.log(\n  await stringify(\n    {\n      title: 'Test recording',\n      steps: [\n        {\n          type: 'navigate',\n          url: 'https://wikipedia.org',\n        },\n      ],\n    },\n    {\n      extension: new Extension(),\n      indentation: '\t', // use tab to indent lines\n    }\n  )\n);\n```\n\n## Others\n\n### Test your extensions using the replay lib\n\nThe replay lib offers a canonical recording and a test page that allows to\nverify that your extension produces all expected side effects on a page.\n\nThe test command supports both stringify and runner extensions. The stringify\nextension will be tested by running the stringified script using node. Run the\ntest using the following command.\n\n```\nnpx -p @puppeteer/replay replay-extension-test --ext path-to-your-extension-js\n```\n\n### Create a Chrome extension for Recorder (Available from Chrome 104 onwards)\n\nYou can create a Chrome extension for [Recorder](https://goo.gle/devtools-recorder). Refer to the [Chrome Extensions documentation](https://developer.chrome.com/docs/extensions/mv3/devtools/) for more details on how to extend DevTools.\n\nFor example, here are some of the third party extensions:\n\n- [Cypress extension](https://chrome.google.com/webstore/detail/cypress-chrome-recorder/fellcphjglholofndfmmjmheedhomgin) lets you export JSON user flows as [Cypress test script](https://github.com/cypress-io/cypress-recorder-extension). [Cypress](https://cypress.io) is a front end testing tool built for the modern web.\n- [WebPageTest extension](https://chrome.google.com/webstore/detail/webpagetest-recorder-exte/eklpnjohdjknellndlnepihjnhpaimok) lets you export user flows from the Recorder directly as [WebPageTest Custom scripts](https://docs.webpagetest.org/scripting/) to measure site's performance. See [Converting user flows to WebPageTest custom scripts](https://blog.webpagetest.org/posts/introducing-the-new-webpagetest-recorder-chrome-extension/) to learn more.\n- [Nightwatch extension](https://chrome.google.com/webstore/detail/nightwatch-chrome-recorde/nhbccjfogdgkahamfohokdhcnemjafjk/) lets you export JSON user flows as [Nightwatch test script](https://github.com/nightwatchjs/nightwatch-recorder-extension). [Nightwatch](https://nightwatchjs.org/) is an end-to-end testing solution for web applications and websites.\n- [Testing Library extension](https://chrome.google.com/webstore/detail/testing-library-recorder/pnobfbfcnoeealajjgnpeodbkkhgiici) lets you export JSON user flows as [Testing Library script](https://github.com/nickmccurdy/testing-library-recorder-extension). [Testing Library](https://testing-library.com/) has simple and complete testing utilities that encourage good testing practices.\n- [WebdriverIO extension](https://chrome.google.com/webstore/detail/webdriverio-chrome-record/pllimkccefnbmghgcikpjkmmcadeddfn?hl=en\u0026authuser=1) lets you export JSON user flows as [WebdriverIO test script](https://github.com/webdriverio/recorder-extension). [WebdriverIO](https://webdriver.io/) is an end-to-end testing solution for web, mobile and IoT applications and websites.\n\nThis feature only available from Chrome 104 onwards. Check your current Chrome version with `chrome://version`. Consider installing [Chrome Canary](https://www.google.com/chrome/canary/) to try out cutting-edge features in Chrome.\n\nThis repository contains an [example extension](https://github.com/puppeteer/replay/tree/main/examples/chrome-extension). Once installed, the Recorder will have a new export option **Export as a Custom JSON script** in the [export dropdown](https://developer.chrome.com/docs/devtools/recorder/#export-flows).\n\nTo load the example into Chrome DevTools. Follow these steps:\n\n1. Download the [chrome-extension](https://github.com/puppeteer/replay/tree/main/examples/chrome-extension) folder.\n2. [Load the folder as unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/#unpacked) in Chrome.\n3. [Open a recording](https://developer.chrome.com/docs/devtools/recorder/#record) in the Recorder.\n4. Click on [export](https://developer.chrome.com/docs/devtools/recorder/#export-flows). Now you can see a new **Export as a Custom JSON script** option in the export menu.\n\nClick and watch the video demo below:\n\n[![Demo video that shows how to extend export options in Recorder panel by adding a Chrome extension](https://user-images.githubusercontent.com/5917927/172872574-15ad8bea-142a-4972-bf1d-bf1379a955ba.png)](https://youtu.be/TCxIfbxgypQ)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppeteer%2Freplay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppeteer%2Freplay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppeteer%2Freplay/lists"}