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

# Migrate from Cypress

> Convert your Cypress test suite to TesterArmy AI-powered tests with a single agent prompt. Replace cy.get selectors and custom commands with natural-language steps.

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](/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](/auth/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](/run/videos) on every run                                    |
| CI job running `cypress run`                        | `ta tests run --group <groupId>` or [group webhooks](/run/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](/run/prep-test) or seed your staging environment before runs 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 Cypress tests:

```txt
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> --local --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 read like instructions for a human tester.
2. Add [credentials](/auth/credentials) for the logins your custom commands handled.
3. If your suite relied on seeding, set up a [preparation test](/run/prep-test) that runs before the group.
4. Replace the `cypress run` CI job with `ta tests run --group <groupId>` or a [group webhook](/run/group-webhooks), then remove the Cypress dependency once runs are green.

## Next steps

#### [CLI Getting Started](/cli)

Install, authenticate, and run your first test.

#### [Agentic Usage](/cli/agentic-usage)

How coding agents drive the TesterArmy CLI.

#### [Preparation Test](/run/prep-test)

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

#### [Pull Request Testing](/run/pull-request-testing)

Run migrated tests on every PR.