qamigrate

Migrate Java Selenium test suites to Playwright Java, with proof that the migration worked.

qamigrate is a command-line tool for teams moving a Java Selenium project to Playwright Java. It converts the code it can convert safely, marks what needs a human, checks that the result builds and runs, and can undo everything. It is not a one-click converter: it is built to make a migration measurable and reversible.

• Assess a Selenium project: what it uses, how risky it is to migrate, and what can be automated.
• Baseline the original suite so you know it was healthy before you started.
• Migrate with deterministic, rule-based rewrites, and leave TODO(qamigrate) review markers wherever an automatic change would not be safe.
• Verify that the migrated project compiles, its tests are discovered, and, optionally, that a real browser test passes on Playwright.
• Report confidence and remaining work in HTML, Markdown, and JSON.
• Roll back to your original files at any time.

Requirements

• Node.js 20 or newer to run qamigrate.
• A Maven project that uses Selenium WebDriver with TestNG, JUnit 5, or JUnit 4.
• A JDK and Maven to build that project, the same ones your Selenium suite already uses.

Gradle projects are detected but not migrated yet.

Install

npm install -g qamigrate

Or run it without installing:

npx qamigrate --help

Quick start

Run each step from anywhere, pointing --project at your Maven project. qamigrate never touches a file until migrate, and keeps backups when it does.

qamigrate init --project ./my-selenium-tests
qamigrate analyze --project ./my-selenium-tests
qamigrate baseline --project ./my-selenium-tests
qamigrate plan --project ./my-selenium-tests
qamigrate migrate --project ./my-selenium-tests --mode hybrid --dry-run
qamigrate migrate --project ./my-selenium-tests --mode hybrid
qamigrate verify --project ./my-selenium-tests
qamigrate report --project ./my-selenium-tests

| Command | What it does | |---|---| | init | Creates the .qamigrate/ workspace and a qamigrate.yml configuration file | | analyze | Inventories the project: Selenium usage, architecture, and a risk map | | baseline | Builds the original project (and optionally runs sample tests) before anything changes | | plan | Produces a migration plan with confidence and recommended mode | | migrate | Applies the plan; --dry-run previews patches without changing files | | verify | Builds the migrated project, checks test discovery, and can run sample tests in a real browser | | report | Writes HTML, Markdown, and JSON reports | | rollback | Restores the original files; refuses to overwrite files you edited since, unless --force |

Run qamigrate <command> --help for every option.

Migration modes

| Mode | Use it when | |---|---| | native | You want idiomatic Playwright code only. Anything that cannot be converted natively gets a review marker. | | hybrid (default) | You want native conversions where possible, plus temporary compatibility adapters so the rest keeps working while you finish the migration. | | compat | You want the project running on Playwright quickly through the compatibility adapters, with native rewrites to follow. |

Proving it runs in a browser

verify can run one of your tests after migration and confirm it drives a real browser through Playwright:

qamigrate verify --project ./my-selenium-tests --sample-tests --sample-command "mvn test -Dtest=LoginTest" --sample-browser true --install-browsers

Before running it, qamigrate checks that the exact Playwright browser build is installed and tells you how to install it if not.

What qamigrate converts

Converted automatically

• Browser start-up and shutdown in a BaseTest or a simple DriverManager, including ThreadLocal driver holders
• Page objects with stored By locators, explicit waits, and fluent page objects that return other pages
• PageFactory @FindBy fields, List<WebElement>, and Selenium Select dropdowns
• Common locators, actions, waits, screenshots, window, alert, and frame helpers
• The Playwright Java dependency in your pom.xml

Partially supported

• Frameworks whose helpers take Selenium By parameters (for example click(By)): they run on Playwright through a compatibility adapter rather than being rewritten to native Playwright code.
• Layered enterprise frameworks with several driver factories, and Spring-injected drivers: parts are converted, and the rest is marked for review.
• Cucumber: supported step-definition and navigation patterns only.

Not supported yet

• Gradle builds, full Cucumber migration, and languages other than Java
• Cloud-provider Selenium setups (for example Selenium Grid or vendor capabilities): detected and reported, not converted

When qamigrate is not sure a change is safe, it leaves the code as it was and adds a TODO(qamigrate) review marker explaining why. It checks every lifecycle rewrite before writing it and discards any rewrite that would not compile.

Configuration

init creates qamigrate.yml in your project. It controls the migration mode, locator and wait strategy, risk thresholds, sample tests for baseline and verify, browser checks, and report formats.

qamigrate keeps its own files in a .qamigrate/ folder in your project:

.qamigrate/
|-- analysis/   project inventory, Selenium usage, architecture, risk map
|-- plans/      migration plan
|-- patches/    generated patches and transformation results
|-- reports/    HTML, Markdown, and JSON reports
|-- backups/    original files and the rollback manifest
|-- logs/
`-- state.json

Add .qamigrate/ to your .gitignore.

Privacy and Telemetry

qamigrate runs locally. Your code and project files never leave your machine.

qamigrate can optionally share anonymous usage data with QATonic. It is off unless you opt in: on the first interactive run, qamigrate asks once, and the default answer is no. When on, each command sends only:

• the command name (init, analyze, baseline, plan, migrate, verify, report, rollback) and, for migrate, the mode
• the exit code, success, and duration
• the qamigrate version, operating system, CPU architecture, and Node.js major version
• a random install ID created when you opt in (deleted when you opt out)

It never sends your code, file paths, project or host names, or user names. Data goes to QATonic's PostHog project (US), which is configured to discard the IP address of incoming requests, so no IP address or location is stored. Nothing is sent during npm install.

qamigrate telemetry            # show status and what is collected
qamigrate telemetry enable     # opt in
qamigrate telemetry disable    # opt out

Telemetry is always off when DO_NOT_TRACK=1 or QAMIGRATE_TELEMETRY=0 is set, and in CI unless QAMIGRATE_TELEMETRY=1 is set. Your choice is stored in %APPDATA%\qamigrate\telemetry.json on Windows and ~/.config/qamigrate/telemetry.json elsewhere, never in your project.

License

Copyright QATonic Innovations. All rights reserved. qamigrate is proprietary software published as UNLICENSED. For licensing terms, contact QATonic Innovations.

Release history: see CHANGELOG.md.