> 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/migration.md).

# Migration Overview

Choose a safe ContextQA migration path for Playwright, Selenium, Tricentis Tosca, or mabl while preserving assertions, data, evidence, and rollback.

## Quick answer

A safe migration preserves the business behavior, assertions, test data, environment assumptions, and evidence needed for a release decision—not just the old tool’s step count. ContextQA can analyze supported code repositories through its documented MCP migration workflow. For proprietary or unsupported source formats, use a staged conversion: inventory the source, extract human-readable intent and evidence, rebuild a representative slice, compare results in parallel, and migrate only after acceptance and rollback gates pass.

## Choose your source

| Source                     | Recommended starting path                                                             | Important boundary                                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Playwright repository      | [Migrate Playwright tests](/migrate-to-contextqa/playwright-to-contextqa.md)          | Helpers, fixtures, custom code, projects, and assertions require review even when repository analysis succeeds                     |
| Selenium repository        | [Migrate Selenium tests](/migrate-to-contextqa/selenium-to-contextqa.md)              | Page objects, waits, framework hooks, and external libraries may not map one-to-one                                                |
| Tricentis Tosca            | [Migrate from Tricentis Tosca](/migrate-to-contextqa/tricentis-tosca-to-contextqa.md) | No direct Tosca-subset importer is documented here; preserve business intent and rebuild through a controlled conversion           |
| mabl                       | [Migrate from mabl](/migrate-to-contextqa/mabl-to-contextqa.md)                       | mabl can export some browser tests to Playwright, Selenium IDE, JSON, or CSV, but its documented export has unsupported step types |
| Mixed or another framework | [Migration planning checklist](/migrate-to-contextqa/planning-checklist.md)           | Classify each source asset before choosing direct analysis, intermediate export, or manual reconstruction                          |

Keeping execution in your own repository? Use the [Cypress-to-Playwright migration guide](/testing-with-ai-coding-agents/cypress-to-playwright.md) to preserve assertions, request behavior, authentication, and saved state. That guide starts with a framework-to-framework example and then explains an optional ContextQA evaluation.

## The three migration paths

```mermaid
flowchart TD
    A[Source suite] --> B{Supported code repository?}
    B -- Yes --> C[MCP analysis and dry run]
    B -- No --> D{Usable intermediate export?}
    D -- Yes --> E[Export, inspect, then analyze or reconstruct]
    D -- No --> F[Intent-led manual reconstruction]
    C --> G[Representative migrated slice]
    E --> G
    F --> G
    G --> H[Parallel comparison]
    H --> I{Acceptance gates pass?}
    I -- Yes --> J[Wave migration]
    I -- No --> K[Remediate, narrow, or stop]
```

### Direct repository analysis

Use the [MCP-assisted migration workflow](/migrate-to-contextqa/migrating-existing-tests.md) for a supported Selenium, Cypress, Playwright, or Jest repository. Analyze first, run a dry run, inspect skipped tests, then migrate a small set.

“Supported analysis” does not mean lossless conversion. Review generated steps and required assertions against the source.

### Intermediate export

Some platforms export browser tests into code or a structured file. Treat the export as an input candidate:

1. Read the source vendor’s current export limitations.
2. Compare exported and source test inventories.
3. Identify unsupported steps, data, reusable components, and assertions.
4. Run the export independently when possible.
5. Analyze or reconstruct only after the intermediate artifact passes review.

An intermediate export can lose semantics before ContextQA ever sees it. Preserve the source record until the migrated test passes its acceptance checks.

### Intent-led reconstruction

Use this path for proprietary, binary, heavily model-based, or unsupported source assets. Extract:

* requirement or business-risk link;
* preconditions and user role;
* ordered actions;
* positive, negative, and persisted-state assertions;
* data and environment dependencies;
* current execution evidence; and
* cleanup or rollback behavior.

Rebuild the smallest representative workflow first. Do not translate proprietary implementation details that no longer serve the business intent.

## Preserve the migration unit

The migration unit is not “one old test equals one new test.” Use a behavior packet:

```
Behavior ID:
Requirement or business risk:
Source test and revision:
Preconditions:
Role and tenant:
Data setup/reset:
Actions:
Required assertions:
Negative and boundary cases:
Environment/browser/device matrix:
Source run evidence:
ContextQA test/suite/plan references:
Known unsupported behavior:
Owner and reviewer:
```

One source test may become several ContextQA cases when it contains unrelated behaviors. Several repetitive source tests may become one parameterized case with a reviewed data profile.

## Use migration waves

| Wave                     | Content                                                         | Purpose                                                             |
| ------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------- |
| 0 — inventory            | Suite map, dependencies, evidence, owners                       | Establish scope and find unknowns                                   |
| 1 — representative pilot | 5–15 tests across easy, complex, negative, and data-heavy cases | Test the conversion method                                          |
| 2 — release-critical     | Stable, high-value workflows                                    | Prove parallel-run and gate behavior                                |
| 3 — broader regression   | Remaining supported tests                                       | Scale with measured review capacity                                 |
| 4 — specialist/legacy    | Rare, proprietary, or low-value cases                           | Rebuild, retain, replace with another control, or retire explicitly |

Do not start with the easiest hundred tests and call the migration validated. Include at least one case that exposes fixtures, data, permissions, custom logic, and failure diagnostics.

## Acceptance gates

Every wave should pass these gates:

| Gate                | Required evidence                                                       |
| ------------------- | ----------------------------------------------------------------------- |
| Inventory           | Every source test has a disposition and owner                           |
| Assertion integrity | Critical expected outcomes are reviewed in ContextQA                    |
| Failure fidelity    | A reversible seeded defect fails for the intended reason                |
| Environment parity  | Build, data, identity, network, browser/device, and locale are recorded |
| Evidence            | Reviewers can open the run and required artifacts                       |
| Operating fit       | Creation, review, triage, and maintenance effort are measured           |
| Parallel comparison | Source and candidate divergences are classified                         |
| Rollback            | The source path remains runnable through the acceptance window          |
| Portability         | Export and residual dependencies are documented when required           |

Use the complete [migration planning checklist](/migrate-to-contextqa/planning-checklist.md) to record these gates.

## What not to carry forward automatically

* sleeps or waits that only compensate for source-runner behavior;
* selectors when the migrated step should express stable user intent;
* retries that hide a deterministic defect;
* duplicated tests with no distinct risk or environment;
* credentials embedded in source code, spreadsheets, or exported files;
* old execution history without its build and environment context; and
* vendor-specific recovery logic that weakens an assertion.

Retiring an obsolete test is acceptable when the decision and rationale are recorded. Silent omission is not.

## Definition of done

A migration is complete when:

* the source inventory reconciles to migrated, retained, replaced, or retired dispositions;
* critical requirements map to reviewed ContextQA assertions;
* representative normal and seeded-failure runs behave as expected;
* test data, environment, browser/device, and credential ownership are documented;
* the CI/release path distinguishes pass, fail, and unknown outcomes;
* reviewers can reach the required evidence;
* overlap results and unresolved divergences are signed off; and
* rollback and exit/portability records are complete.

## Related documentation

* [Migration planning checklist](/migrate-to-contextqa/planning-checklist.md)
* [AI testing pilot scorecard](/evaluation-and-governance/ai-testing-pilot-scorecard.md)
* [Test data management](/web-testing/test-data-management.md)
* [Test Plans](/web-testing/test-plans.md)
* [Test results](/reporting/test-results.md)

{% hint style="info" %}
**Want to test the migration path on your hardest representative workflow?** [**Book a migration assessment →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=migration_hub) — Bring one source test, its fixtures, and a recent failure record. We will help define the smallest evidence-bearing pilot.
{% 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/migration.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.