> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/migrate-to-contextqa/selenium-to-contextqa.md).

# 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.

## Key takeaways

* Migrate Selenium from a versioned repository, not from a list of test names.
* Record: Run the source cohort at that exact revision.
* Selenium is a browser automation library used through many languages and test runners.

## 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](https://www.selenium.dev/documentation/webdriver/waits/).

| 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](/evaluation-and-governance/browser-grid-migration-checklist.md) 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

<details>

<summary>The analyzer reports fewer tests than the runner</summary>

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.

</details>

<details>

<summary>A migrated test is shorter than the Selenium source</summary>

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.

</details>

<details>

<summary>Should every sleep become a ContextQA step?</summary>

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

</details>

## Related documentation

* [Migration overview](/migrate-to-contextqa/migration.md)
* [Migration planning checklist](/migrate-to-contextqa/planning-checklist.md)
* [MCP-assisted suite migration](/migrate-to-contextqa/migrating-existing-tests.md)
* [Browser-grid migration checklist](/evaluation-and-governance/browser-grid-migration-checklist.md)
* [Debugging tests](/execution/debugging-tests.md)

{% hint style="info" %}
**Want to test the Selenium migration on a page-object-heavy workflow?** [**Book a migration review →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=selenium_migration) — Bring the test, its page objects, waits, and current Grid capabilities.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/migrate-to-contextqa/selenium-to-contextqa.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.