Migrate from Selenium | TesterArmy: Documentation

Selenium suites are the oldest and usually the heaviest: page object classes, WebDriverWait with expected conditions, driver management, Grid infrastructure, and locator strategies spread across hundreds of files in Java, Python, or C#. Most of that code exists to work around one problem - scripted automation can’t see the page.

TesterArmy’s agent can. Tests are natural-language steps executed with vision, so there are no locators, waits, or page objects to maintain, and no browser infrastructure to run. The fastest migration path is letting your coding agent (Claude Code, Cursor, Codex) read your Selenium suite and convert it with the TesterArmy CLI.

How concepts map

Selenium	TesterArmy
A test method (JUnit/TestNG/pytest/NUnit)	A test with natural-language steps
Test class / suite XML	A test group
`driver.get()`, `element.click()`, `sendKeys()`	`act` steps (“Open /orders”, “Enter the search term”)
Framework assertions on page state	`assert` steps (“The order appears in the table”)
Login helpers / auth page objects	`login` step + project credentials
Page Object Model classes	Not needed - the intent in their method names becomes step text
`By.id`, `By.xpath`, `By.cssSelector` locators	Not needed - the agent finds elements visually
`WebDriverWait` + `ExpectedConditions`	Not needed - the agent waits like a human
Selenium Grid / driver binaries	Nothing to manage - runs locally via the CLI or in TesterArmy cloud
CI job running the suite	`ta tests run --group <groupId>` or group webhooks

What translates and what doesn’t

The page object pattern actually makes migration easier: method names like loginPage.submitValidCredentials() or cartPage.removeFirstItem() already describe user intent, which is exactly what TesterArmy steps are.

Things to leave behind:

Driver and Grid management - capabilities, driver factories, Dockerized Grids. There is no equivalent because none of it is needed.
Cross-browser matrices - the TesterArmy agent tests behavior, not browser quirks. Run locally with --browser firefox if you still need a second engine.
Database setup/teardown hooks - seed staging ahead of runs or use a preparation test.

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 Selenium tests. It works for Java, Python, C#, Ruby, and JavaScript bindings:

Migrate this repository's Selenium WebDriver 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 all Selenium test classes/modules (JUnit/TestNG, pytest,
   NUnit, RSpec, or Mocha bindings), page object classes, and the base URL
   (config files, properties, env vars, or driver.get() calls).
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, and domain knowledge
   encoded in page objects (e.g. "Admin settings live under /admin,
   reachable only after login").
   echo '{"category":"site_structure","title":"...","content":"...","importance":"high"}' | ta memories create --project <projectId> --json
4. Convert each test method into a TesterArmy test:
   - Express the USER INTENT in plain English. Use page object method
     names as a guide - submitValidCredentials() becomes "Log in with
     valid credentials". Drop all locators (By.id, XPath, CSS),
     WebDriverWait/ExpectedConditions, Thread.sleep, and retry logic - the
     TesterArmy agent finds elements visually and waits on its own.
   - driver.get / click() / sendKeys() / select -> steps with type "act"
   - assertEquals/assertTrue/expect on page state -> steps with type "assert"
   - login helpers and auth setup -> one step with type "login"
   - Keep tests focused: 3-10 steps. Split long scenario methods into
     separate tests.
   - Skip pure API tests and unit tests of page object utilities.
   Create each test:
   echo '{"title":"<test name>","description":"Migrated from <class/file>","steps":[{"title":"Open /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 the suite reads credentials
   from properties files or env vars, 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: test class/method -> 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 - steps should read like manual test cases, because that’s what they are now.
Add credentials for the logins your auth helpers handled.
Replace the Selenium CI job (and the Grid behind it) with ta tests run --group <groupId> or a group webhook.
Decommission driver binaries, Grid containers, and the page object layer once 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.

Group Webhooks

Trigger migrated suites from any CI system.

Test Credentials

Store logins securely instead of in properties files.