Migrate from Puppeteer | TesterArmy: Documentation

Puppeteer scripts are imperative browser automation: page.waitForSelector, page.$eval, manual retries, and assertions bolted on through Jest or plain Node scripts. They work until the DOM changes, and then someone spends an afternoon updating selectors.

TesterArmy replaces scripted automation with an AI agent that executes natural-language steps using vision. The fastest migration path is letting your coding agent (Claude Code, Cursor, Codex) read your Puppeteer code and convert it with the TesterArmy CLI.

How concepts map

Puppeteer	TesterArmy
A script or `it()` block driving `page`	A test with natural-language steps
`page.goto()`, `page.click()`, `page.type()`	`act` steps (“Go to /checkout”, “Type the coupon code”)
Jest `expect()` on `page.$eval` / `page.content()`	`assert` steps (“The total shows the discount”)
Manual login sequences / cookie injection	`login` step + project credentials
`page.waitForSelector()`, `waitForNavigation()`	Not needed - the agent waits like a human
CSS/XPath selectors	Not needed - the agent finds elements visually
`page.screenshot()` for evidence	`screenshot` step (every run also records video)
`puppeteer.launch({ headless: false })` debugging	`ta tests run <testId> --headed`

What translates and what doesn’t

End-to-end user flows translate cleanly - the intent behind each page.* call becomes an act step and each assertion becomes an assert step.

Things to leave behind:

Scraping and PDF generation scripts - Puppeteer is the right tool for those; TesterArmy is for testing user flows.
Request interception (page.setRequestInterception) - TesterArmy runs against a real environment such as staging or a preview deployment.
Low-level browser tweaks (custom user agents, CDP sessions) - configure environment-level needs like viewport size per project instead.

Prerequisites

$ npm install -g testerarmy
$ ta auth

Get an API key from the dashboard. For non-interactive agent sessions, set TESTERARMY_API_KEY instead.

The migration prompt

Paste this into your coding agent in the repository that contains your Puppeteer tests:

Migrate this repository's Puppeteer tests to TesterArmy using the
TesterArmy CLI (`ta`). Verify auth first with `ta status --json`, and use
`ta --help` plus subcommand help to discover commands. Prefer --json output.
1. Discover: find all files importing puppeteer or puppeteer-core
   (Jest-Puppeteer suites, *.e2e.js scripts, jest-puppeteer.config.js).
   Identify the base URL from config, env vars, or page.goto() calls.
   Only migrate files that TEST user flows - skip scrapers, PDF/screenshot
   generators, and crawling utilities.
2. Create a TesterArmy project (skip if one exists in `ta projects list`):
   echo '{"name":"<repo name>","url":"<base URL>","projectType":"web"}' | ta projects create --json
3. Save durable context as project memories (category site_structure,
   importance high): key routes, the login URL, setup steps from
   beforeAll/globalSetup that describe the app.
   echo '{"category":"site_structure","title":"...","content":"...","importance":"high"}' | ta memories create --project <projectId> --json
4. Convert each test/script into a TesterArmy test:
   - Express the USER INTENT of each action in plain English. Drop all
     selectors, waitForSelector/waitForNavigation calls, sleeps, and retry
     loops - the TesterArmy agent finds elements visually and waits on its
     own.
   - page.goto/click/type/select -> steps with type "act"
   - expect() assertions on page content -> steps with type "assert"
   - manual login sequences or cookie injection -> one step with type "login"
   - page.screenshot() evidence points -> steps with type "screenshot"
   - Keep tests focused: 3-10 steps. Split long scripts that cover
     multiple flows into separate tests.
   Create each test:
   echo '{"title":"<test name>","description":"Migrated from <file>","steps":[{"title":"Navigate to /login","type":"act"},{"title":"Dashboard loads","type":"assert"}]}' | ta tests create --project <projectId> --json
   Step types: act, assert, login, screenshot.
5. Never hardcode passwords in test steps. If scripts read credentials from
   env vars or inject cookies, tell me which credentials to add and I will run:
   echo '{"kind":"login","label":"...","username":"...","password":"..."}' | ta projects credentials-create <projectId> --json
6. Verify: run each migrated test locally with
   `ta tests run <testId> --url <base URL> --json` and report results.
   Exit code 0 = pass, 1 = fail.
7. Report a summary table: source file -> TesterArmy test ID -> run result,
   plus a list of anything you intentionally skipped and why.

After the migration

Review the migrated tests in the dashboard - step titles should describe intent, not DOM structure.
Add credentials for any login flows the agent flagged.
Replace your Puppeteer CI job with ta tests run --group <groupId> or a group webhook.
Keep Puppeteer for scraping or PDF work; delete the test scripts once TesterArmy runs are green.

Next steps

CLI Getting Started

Install, authenticate, and run your first test.

Agentic Usage

How coding agents drive the TesterArmy CLI.

Run Videos

Every run records video - better than screenshot debugging.

Test Credentials

Store logins securely instead of in scripts.