Migrate from Selenium

Inventory Selenium runners, page objects, waits, grids, data, and assertions; migrate a representative slice to ContextQA and verify behavior safely.

Quick answer

Migrate Selenium from a versioned repository, not from a list of test names. Identify the language and runner, page objects, waits, browser capabilities, Grid settings, data setup, helpers, and assertions; then use ContextQA’s MCP analysis and dry run for the supported repository. Translate business intent rather than copying locators or sleeps, map every external dependency, and verify the migrated case against the same build with both a passing control and a deliberately failing control.

Establish the source baseline

Record:

Repository and full commit SHA:
Language/runtime version:
Selenium version:
Test runner and version:
Dependency manifest/lockfile:
Test and page-object paths:
Default local command:
CI command:
Grid/driver configuration:
Required browser/capability matrix:
Baseline report and artifacts:
Suite owner:

Run the source cohort at that exact revision. Preserve the test runner report, browser/driver versions, Grid session information when applicable, and failure diagnostics.

Inventory the Selenium architecture

Selenium is a browser automation library used through many languages and test runners. The repository structure, not the word “Selenium,” determines the migration work.

Runner and lifecycle

Area	Source value	Migration effect
Language	Java / Python / C# / JavaScript / Ruby / other	Parser and helper review
Runner	JUnit / TestNG / pytest / NUnit / Mocha / other	Discovery, parameterization, setup, and result semantics
Setup scope	Test / class / suite / session	Destination prerequisite and cleanup design
Parallelism	Processes, threads, workers, Grid sessions	Test-plan capacity and data isolation
Retry plugin	Name and policy	Initial-versus-final result visibility
Reporter	JUnit XML, Allure, custom	Evidence and retention comparison

Page objects and helpers

Object/helper	Methods used	Hidden waits/assertions	Data or side effects	ContextQA treatment
				Natural-language steps / API setup / custom code / retained

Do not translate a page-object method by its name alone. Read whether it includes conditional navigation, retries, JavaScript execution, frame/window switching, or assertions.

Waits and synchronization

Selenium’s official documentation identifies race conditions between the application and commands as a common cause of flaky tests. Inventory implicit waits, explicit waits, fluent waits, fixed sleeps, page-load strategies, and custom polling. See Selenium waiting strategies.

Source wait	Why it exists	Observable ready condition	ContextQA treatment	Reviewer
sleep(5000)	Unknown	Replace with investigated condition	Do not copy blindly
Element visible	UI readiness	Named control is visible/enabled	Express in step or assertion
API response complete	Data readiness	Stable network or UI state	API prerequisite or explicit condition
Download present	File completion	File and contents available	Verify supported workflow separately

Remove a wait only when the migrated workflow has another observable readiness condition. Removing every wait without understanding it can turn flakiness into false failures.

Browser and Grid capabilities

Capability	Required value	Current Grid/driver source	ContextQA mapping	Observed?
Browser/version			Test-plan machine / external remote profile / retain
OS/device
Resolution
Locale/timezone
Proxy/certificate			Proxy/remote-browser profile / retain
Downloads/uploads			Verify scenario
Concurrency			Workspace/external capacity

Use the browser-grid migration checklist before changing Grid ownership.

Step 1: Analyze without changing the workspace

From an approved MCP client:

Analyze the Selenium test repository at <absolute path> at commit <full SHA>.
Do not migrate tests. Report the detected language/framework, estimated test
count, runner/config files, page-object and helper directories, unsupported
patterns, and files not analyzed.

Reconcile the count with the inventory. Mixed frameworks, generated tests, nonstandard naming, or runner-specific factories may require a narrower path or manual inventory.

Step 2: Dry-run a representative cohort

Choose:

• one linear UI case;
• one page-object-heavy case;
• one parameterized/data-provider case;
• one frame, window, shadow DOM, download, or file-upload case if required;
• one test with API/database setup;
• one negative permission case; and
• one historically flaky test.

Preview migration of <pilot path or selected files> from Selenium to ContextQA
workspace <reference>. Use dry-run mode. Return proposed cases, migrated and
skipped counts, skip reasons, and make no other workspace changes.

Treat an unsupported case as a planning result. Decide whether to reconstruct it, keep it in Selenium, replace it with another control, or retire it with approval.

Step 3: Map source mechanics to ContextQA

Selenium source	ContextQA destination	Acceptance check
Locator sequence	Intent-based test steps	Does the step identify a stable user action?
Assertion library	Verification step, API assertion, or custom code	Is the business outcome preserved exactly?
Page object	Several steps or reusable approved pattern	Are hidden branches and waits visible?
Data provider	Test data profile	Are rows isolated, synthetic, and resettable?
Environment property	Environment variable	Is the correct build/config used?
Secret	Password/vault or CI secret	Is the value absent from test text/evidence?
Setup/teardown hook	Prerequisite, API step, cleanup workflow, or retained job	Does failure stop the test visibly?
Grid capabilities	Test-plan machine or verified remote-browser profile	Does observed coverage match the requirement?
JavaScript executor	Supported step/custom code/manual redesign	Is the behavior a user contract or implementation workaround?
Runner retry	Plan/test setting and team release policy	Are first failure and retry visible?

Step 4: Create and review the pilot

After the real migration returns created ContextQA test references:

1. Compare every step with the behavior packet.
2. Inspect assertions in the test method, page objects, and helper libraries.
3. Replace source credentials and URLs with approved ContextQA configuration.
4. Rebuild required setup and cleanup before executing.
5. Group accepted cases into a pilot suite and saved test plan.
6. Keep unreviewed migrated cases outside release-blocking plans.

Step 5: Compare execution

Behavior	Selenium run	ContextQA run	Same build/data?	Assertion result	Evidence difference	Owner

Classify differences as product, test, data, environment, browser/driver, timing, or unknown. A ContextQA pass and Selenium failure—or the reverse—is an investigation trigger, not an automatic winner.

Step 6: Validate readiness and negative controls

For one timing-sensitive case:

1. Remove or delay the expected readiness condition in a disposable fixture.
2. Confirm the migrated test does not pass before the application is ready.
3. Restore the condition and verify a normal pass.
4. Record whether retries were used.

For one critical assertion:

1. Change the expected business result in a disposable build.
2. Verify both the Selenium and ContextQA cases fail for that reason.
3. Restore and rerun.

This distinguishes a stable migration from one that merely stopped exercising the risky condition.

Step 7: Handle what should remain in Selenium

Keep a case in Selenium when it depends on an unverified browser capability, proprietary helper, low-level protocol operation, unsupported integration, or code-review requirement that ContextQA has not demonstrated for the intended use.

Record:

Source test:
Behavior retained:
Reason:
Authoritative runner:
Owner:
Evidence location:
Re-evaluation trigger:

Hybrid ownership is acceptable. Ambiguous ownership is not.

Selenium migration checklist

• Repository, commit, language, runtime, Selenium, runner, and browser/driver versions are recorded.
• Source baseline run and artifacts are preserved.
• Page objects, helpers, hooks, data providers, waits, retries, and reports are inventoried.
• Grid/browser capabilities are mapped through an observed coverage matrix.
• Analyzer count reconciles to the source inventory.
• Dry-run skip reasons are reviewed.
• A difficult representative cohort—not only linear tests—was migrated.
• Assertions hidden outside test methods are preserved.
• Fixed sleeps were investigated instead of copied blindly.
• Data, environment, secrets, setup, and cleanup have named owners.
• Normal, timing, and seeded-defect controls behave as expected.
• Parallel-run divergences and retained Selenium tests are explicit.
• Rollback and source-of-truth decisions are approved.

Common migration traps

The analyzer reports fewer tests than the runner

Check custom factories, parameterized runner features, generated suites, nonstandard naming, nested modules, and mixed frameworks. Keep the source runner’s discovered-test list as the reconciliation baseline.

A migrated test is shorter than the Selenium source

Shorter can be good if locators and plumbing disappeared. It is unsafe if assertions, branches, setup, cleanup, or readiness conditions disappeared. Compare behavior packets and negative controls.

Should every sleep become a ContextQA step?

No. Identify the observable condition the sleep was approximating. Express that condition through the appropriate step, assertion, environment readiness, or retained prerequisite.

Related documentation

• Migration overview
• Migration planning checklist
• MCP-assisted suite migration
• Browser-grid migration checklist
• Debugging tests

Want to test the Selenium migration on a page-object-heavy workflow? Book a migration review → — Bring the test, its page objects, waits, and current Grid capabilities.