# Adapt a Puppeteer script

Canonical: https://fairleadhq.com/docs/recorder/developers/puppeteer-export/

Updated: 2026-10-10
Publication state: published
Product version: Source verified — 52de40a

Agent summary: Adapt recorded actions into a runnable Puppeteer workflow. ES-module setup is required; generated actions are not complete test coverage.

## Prerequisites

- A supplied puppeteer.js file; a compatible Node.js and Puppeteer project

## Inputs

- Generated puppeteer.js and application setup

## Outputs

- An adapted script with checks and repeatability review

## Limitations

- ES-module setup is required; generated actions are not complete test coverage

## Permissions

- Authorization to run scripts against the target environment

## Privacy

- Review logs and recorded values before copying or running artifacts


Adapt recorded actions into a runnable Puppeteer workflow.

Start with the supplied `puppeteer.js` and review it in your own test project before execution.

## Inspect the supplied script

Open `puppeteer.js` from the [shared artifact bundle](https://fairleadhq.com/docs/recorder/developers/artifact-bundle/). Compare it with `session.md` and the expected result. Review the generated file directly for locator risks, redacted values, omitted actions, and comments. It uses Puppeteer directly rather than requiring a DevTools JSON replay runner.

## Prepare the runtime

The generated script uses ECMAScript imports and Puppeteer's locator API; its generated header specifies Puppeteer 25 or later. Use a Node.js environment compatible with the chosen Puppeteer release and configure the project for ES modules, or save a reviewed copy with an `.mjs` extension.

Install and configure Puppeteer following its [getting-started guide](https://pptr.dev/guides/getting-started). Keep dependency setup in your test project.

## Review the conversion

Supported navigation, clicks, fills, control changes, and other converted actions become script statements. Compare the script with the original check to find unsupported actions and incomplete targets.

Review selectors, especially repeated labels, dynamic identifiers, frames, and Shadow DOM. Supply authentication and data setup; initial navigation cannot restore pre-recording state. Replace masked values with safe test inputs.

Keyboard actions and file-upload changes are omitted. Redacted inputs are skipped with comments, so add those steps using safe test data. Generated actions target the page; add frame locators for actions recorded inside iframes.

## Inspect the real sample script

The [sample ZIP](https://fairleadhq.com/downloads/fairlead-recorder-sample-v1.zip) includes `puppeteer.js` for card creation and the Blocked → In progress moves. It uses recorded values and selectors, opens the recorded public URL, and contains no badge assertion. Change the destination and supply your test environment's login and disposable data before execution. Review repeated input events and positional locators against the application.

Add checks that the card is present in In progress and its Blocked badge is absent. A successful sequence of clicks alone misses the defect. The sample's creation request is redacted, so the HAR does not provide complete fixture setup.

## Add checks and run

Add assertions for the intended behavior and appropriate waits and cleanup. Follow [reliable automated tests](https://fairleadhq.com/docs/recorder/developers/reliable-automated-tests/) before treating the script as regression coverage.

In an ES-module project with dependencies available:

```sh
node puppeteer.js
```

Run against an appropriate test environment and inspect the outcome. A script reaching its last line does not prove your acceptance criteria were checked. Repeat from a clean state and investigate locator or precondition failures before changing timing.