> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tester.army/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tester.army/_mcp/server.

# Migrate from Puppeteer

> Convert Puppeteer scripts and Jest-Puppeteer suites to TesterArmy AI-powered tests with a single agent prompt. Drop the selectors and waitForSelector calls.

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](/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](/auth/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](/run/videos)) |
| `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](/run/viewport-size) per project instead.

## Prerequisites

```bash
npm install -g testerarmy
ta auth
```

Get an API key from the [dashboard](https://tester.army/dashboard/profile/api-keys). 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:

```txt
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

1. Review the migrated tests in the [dashboard](https://tester.army/dashboard) - step titles should describe intent, not DOM structure.
2. Add [credentials](/auth/credentials) for any login flows the agent flagged.
3. Replace your Puppeteer CI job with `ta tests run --group <groupId>` or a [group webhook](/run/group-webhooks).
4. Keep Puppeteer for scraping or PDF work; delete the test scripts once TesterArmy runs are green.

## Next steps

Install, authenticate, and run your first test.

How coding agents drive the TesterArmy CLI.

Every run records video - better than screenshot debugging.

Store logins securely instead of in scripts.