Migrate from Cypress | TesterArmy: Documentation

Cypress suites grow into a web of cy.get() selectors, custom commands, fixtures, and intercepts. Every UI change ripples through cypress/e2e, and flake-fighting (cy.wait, retries, { force: true }) becomes its own workstream.

TesterArmy tests are natural-language steps executed by an AI agent with vision - no selectors to maintain, no waits to tune. The fastest migration path is letting your coding agent (Claude Code, Cursor, Codex) read your Cypress suite and convert it with the TesterArmy CLI.

How concepts map

Cypress	TesterArmy
`it()` in a `.cy.ts` / `.cy.js` file	A test with natural-language steps
`describe()` block	A test group
`cy.visit()`, `cy.get().click()`, `cy.get().type()`	`act` steps (“Visit /signup”, “Fill in the email field”)
`cy.contains()`, `should()` assertions	`assert` steps (“A success toast appears”)
`cy.login()` custom commands / `cy.session()`	`login` step + project credentials
`cypress.config.ts` `baseUrl`	Project URL (override with `--url`)
`cypress/support/commands.ts` helpers	Project memories describing the shared flows
`cypress/fixtures` test data	Plain-language data in steps or memories
Cypress Cloud / Dashboard recordings	Run videos on every run
CI job running `cypress run`	`ta tests run --group <groupId>` or group webhooks

What translates and what doesn’t

End-to-end specs translate directly: the user intent behind each cy.* chain becomes an act or assert step, and your selector strategy (data-cy attributes included) is simply dropped.

A few things don’t carry over:

cy.intercept() mocks and stubs - TesterArmy runs against a real environment, so target staging or preview deployments instead of stubbing the network.
Component tests (cy.mount) - keep these in Cypress or move them to a component test runner; TesterArmy is for end-to-end flows.
cy.task() / direct database seeding - use a preparation test or seed your staging environment before runs 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 Cypress tests:

Migrate this repository's Cypress 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: read cypress.config.* for the baseUrl, then find all specs
   under cypress/e2e (*.cy.ts, *.cy.js). Also read
   cypress/support/commands.* and cypress/support/e2e.* to understand
   custom commands like cy.login(), and cypress/fixtures for test data.
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, and what shared custom
   commands do in plain English.
   echo '{"category":"site_structure","title":"...","content":"...","importance":"high"}' | ta memories create --project <projectId> --json
4. Convert each Cypress it() into a TesterArmy test:
   - Express the USER INTENT of each command chain in plain English. Drop
     all selectors (cy.get, data-cy attributes), cy.wait calls, and
     { force: true } workarounds - the TesterArmy agent finds elements
     visually and waits on its own.
   - cy.visit / cy.get().click() / cy.get().type() -> steps with type "act"
   - cy.contains / should() assertions -> steps with type "assert"
   - cy.login() custom commands or cy.session() setup -> one step with
     type "login"
   - Inline the meaning of fixture data ("Fill the form with a valid US
     address") instead of referencing fixture files.
   - Keep tests focused: 3-10 steps. Split it() blocks covering multiple
     flows into separate tests.
   - Skip component tests (cy.mount) and tests that only exercise
     cy.intercept() stubs.
   Create each test:
   echo '{"title":"<test name>","description":"Migrated from <spec file>","steps":[{"title":"Visit /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 Cypress.env() or
   cypress.env.json 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 read like instructions for a human tester.
Add credentials for the logins your custom commands handled.
If your suite relied on seeding, set up a preparation test that runs before the group.
Replace the cypress run CI job with ta tests run --group <groupId> or a group webhook, then remove the Cypress dependency once runs are green.

Next steps

CLI Getting Started

Install, authenticate, and run your first test.

Agentic Usage

How coding agents drive the TesterArmy CLI.

Preparation Test

Replace cy.task() seeding with a prep test.

Pull Request Testing

Run migrated tests on every PR.