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

> Convert your Playwright test suite to TesterArmy AI-powered tests with a single agent prompt. No selectors, no flaky waits, no test maintenance.

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](/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](/auth/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](/run/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

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

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

1. Review the migrated tests in the [dashboard](https://tester.army/dashboard) - step titles should describe intent, not implementation.
2. Add [credentials](/auth/credentials) for any login flows the agent flagged.
3. Organize tests into groups and wire them into CI with [group webhooks](/run/group-webhooks) or `ta tests run --group <groupId>` - see [Pull Request Testing](/run/pull-request-testing).
4. 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

Install, authenticate, and run your first test.

How coding agents drive the TesterArmy CLI.

Run migrated tests on every PR.

Store logins securely instead of in test code.