By QATonic Innovations Pvt Ltd
1. Check the project and tool requirements
This workflow targets a Java Selenium Maven project using TestNG, JUnit 5, or JUnit 4. You need Node.js 20 or newer to run QAMigrate, plus the JDK and Maven used by the existing suite. The current package is distributed through npm, rather than the previous Python implementation.
Start from a clean version-controlled working tree or a disposable branch. Record the baseline commit so the code review can distinguish migration changes from unrelated work. Read the package's licensing terms and current README before use.
npm install -g qamigrate
qamigrate --help2. Inventory the original suite
Point --project at the root of the Maven test project. Initialize the workspace and analyze the suite to understand Selenium usage, architecture, and migration risks. Keep the generated .qamigrate directory out of source control if its contents are local migration artifacts.
Read the analysis before selecting a migration approach. Cloud-provider capabilities, layered driver factories, and framework-specific helper patterns can require follow-up work even when common locators and actions are straightforward.
qamigrate init --project ./my-selenium-tests
qamigrate analyze --project ./my-selenium-tests3. Establish a healthy baseline and a plan
Run baseline on the original project before making migration changes. Investigate existing compilation or test problems first; a migration cannot reliably prove that it preserved behavior if the original suite was already failing.
Generate a plan and review its recommended mode. Native mode focuses on Playwright rewrites, hybrid combines rewrites with temporary compatibility adapters, and compat prioritizes adapter-based execution. Choose based on the analysis and the amount of review your team can do.
qamigrate baseline --project ./my-selenium-tests
qamigrate plan --project ./my-selenium-tests4. Inspect a dry run before applying it
Preview hybrid mode without applying migration patches. Inspect the generated changes and TODO(qamigrate) review markers. Confirm how browser lifecycle, page objects, locators, waits, and dependencies are affected.
Treat unsupported transformations as engineering work to resolve, rather than as a reason to skip verification. Gradle migration, complete Cucumber conversion, non-Java source languages, and cloud-provider Selenium configuration are not fully supported by the current CLI.
qamigrate migrate --project ./my-selenium-tests --mode hybrid --dry-run5. Apply reviewed changes and verify behavior
Once the preview is acceptable, apply the migration without --dry-run. Run verify and report to inspect compilation, test discovery, and the remaining review work. Verification can also run sample tests; consult verify --help and the npm README for browser and sample-command options.
A compiling project is not proof of equivalent test coverage. Run representative browser journeys, inspect assertions and waits, and compare outcomes with the original suite before accepting the changes.
qamigrate migrate --project ./my-selenium-tests --mode hybrid
qamigrate verify --project ./my-selenium-tests
qamigrate report --project ./my-selenium-tests6. Keep a rollback and review trail
QAMigrate keeps backups for rollback. If you need to restore the original files, inspect rollback --help and use the command below. It protects files edited after migration; do not force an overwrite without understanding those later changes.
Review the final diff in version control, record unresolved markers, and run your normal CI checks. The published CLI documentation says source code and project files stay local; optional usage telemetry is off unless you opt in.
qamigrate rollback --project ./my-selenium-tests