Migrate from Playwright | TesterArmy: Documentation

Playwright is a great automation library, but spec files come with a maintenance tax: selectors break when the UI changes, waitFor calls accumulate to fight flakiness, and every refactor of your frontend means a refactor of your tests.

TesterArmy tests are written as natural-language steps. An AI agent with vision executes them against your app, so a renamed data-testid or a redesigned login form doesn’t break anything. The fastest way to migrate is to let your coding agent (Claude Code, Cursor, Codex) read your existing specs and convert them using the TesterArmy CLI.

How concepts map

Playwright	TesterArmy
`test()` in a spec file	A test with natural-language steps
`test.describe()` block	A test group
`page.goto()`, `page.click()`, `page.fill()`	`act` steps (“Navigate to /pricing”, “Click the upgrade button”)
`expect(locator).toBeVisible()` and other assertions	`assert` steps (“The dashboard shows the new project”)
Login fixtures / `storageState`	`login` step + project credentials
`playwright.config.ts` `baseURL`	Project URL (override with `--url`)
Selectors (`getByTestId`, CSS, XPath)	Not needed - the agent finds elements visually
Retries and `waitFor` calls	Not needed - the agent waits like a human
CI workflow running `npx playwright test`	`ta tests run --group <groupId>` or group webhooks

What translates and what doesn’t

Most end-to-end specs translate directly: the user intent in your test() bodies becomes act and assert steps, and selectors are simply dropped.

A few things don’t carry over:

Network mocking (page.route()) - TesterArmy tests run against a real environment, so point them at staging or preview deployments instead of mocks.
Component tests and API-only tests - keep these in Playwright; TesterArmy is for end-to-end user flows.
Heavily parameterized tests - convert the representative cases, not all 50 generated variants.

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 Playwright tests:

Migrate this repository's Playwright test suite 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 playwright.config.* and all spec files (*.spec.ts,
   *.spec.js, *.test.ts under the configured testDir). Read the config to
   determine the baseURL and any storageState/auth setup projects.
2. Create a TesterArmy project (skip if one exists in `ta projects list`):
   echo '{"name":"<repo name>","url":"<baseURL>","projectType":"web"}' | ta projects create --json
3. Save durable context as project memories (category site_structure,
   importance high): key routes, the login URL, anything from global-setup
   files that future test runs should know.
   echo '{"category":"site_structure","title":"...","content":"...","importance":"high"}' | ta memories create --project <projectId> --json
4. Convert each Playwright test() into a TesterArmy test:
   - Express the USER INTENT of each action in plain English. Drop all
     selectors, locators, waitFor calls, and retries - the TesterArmy agent
     finds elements visually and waits on its own.
   - page.goto/click/fill/selectOption -> steps with type "act"
   - expect(...) assertions -> steps with type "assert"
   - login fixtures or storageState setup -> one step with type "login"
   - Keep tests focused: 3-10 steps. Split test() bodies that cover
     multiple flows into separate tests.
   - Skip API-only tests, component tests, and page.route() mocking logic.
   Create each test:
   echo '{"title":"<test name>","description":"Migrated from <spec 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 specs use env vars or
   storageState for auth, 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 <baseURL> --json` and report results.
   Exit code 0 = pass, 1 = fail.
7. Report a summary table: spec 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 implementation.
Add credentials for any login flows the agent flagged.
Organize tests into groups and wire them into CI with group webhooks or ta tests run --group <groupId> - see Pull Request Testing.
Keep Playwright around for component or API tests if you have them; delete the end-to-end specs once the 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.

Pull Request Testing

Run migrated tests on every PR.

Test Credentials

Store logins securely instead of in test code.