> 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/migrating-existing-tests.md). # MCP-Assisted Existing-Suite Migration Analyze a Selenium, Cypress, or Playwright repository, preview an MCP-assisted ContextQA migration, migrate the tests, and verify the results. ## Quick answer Analyze a Selenium, Cypress, or Playwright repository, preview an MCP-assisted ContextQA migration, migrate the tests, and verify the results. Use this page to understand when the capability applies, complete its user-facing workflow, and verify the expected result. ## What this page covers {% hint style="info" %} **Who is this for?** Developers and SDETs who already maintain a Selenium, Cypress, or Playwright suite and want to move it into ContextQA without rewriting every test by hand. {% endhint %} {% hint style="warning" %} Start with the source-neutral [Migration Overview](/migrate-to-contextqa/migration.md). Repository analysis is available only when the required tools appear in your connected MCP manifest and the agent can access the source safely. Review fixtures, helpers, assertions, data, skipped assets, and custom code; conversion is not automatically lossless. {% endhint %} This guide walks through an MCP-assisted migration: make the repository available through an approved execution environment, analyze it, preview conversion, and verify the resulting ContextQA cases. A Playwright export can support a separate portability evaluation, but conversion and export are not guaranteed to preserve every assertion, fixture, or control-flow construct. Migration runs through the ContextQA MCP server, so an AI assistant such as Claude Code, Claude Desktop, or Cursor calls the tools on your behalf. You describe what you want in plain English; the agent selects the right tool and fills in the parameters. By the end of this guide you will have: 1. Analyzed your existing repository to see what will migrate. 2. Previewed the migration with a dry run. 3. Migrated the suite into a ContextQA workspace. 4. Verified the migrated test cases by running one. ## Prerequisites * A ContextQA account with at least one workspace ([sign up at contextqa.com](https://contextqa.com)). * The MCP server connected to your AI assistant. If you have not done this, complete [Tutorial: Create your first test with an AI agent](/mcp-server/first-test-tutorial.md) first. * An existing test repository accessible to the configured analysis and migration service. Confirm supported frameworks in the connected tool schema; framework detection does not establish execution parity. * The base URL of the application your tests target — for example, `https://staging.example.com`. * Familiarity with [core concepts](/getting-started/core-concepts.md) — specifically test cases, steps, and workspaces. {% hint style="info" %} **Confirm filesystem access.** A hosted MCP service does not automatically see your coding client's local checkout. Verify which service reads `repo_path`, how access is provided, and which source data leaves your machine. The paths below are illustrative paths in that configured execution environment. {% endhint %} *** ## How migration works Migration does not mean running the original test runner unchanged. The service parses supported constructs and creates ContextQA cases; review the retained actions, assertions, and omitted dependencies. Three MCP tools cover analysis, conversion, and export: | Tool | Purpose | | --------------------------- | ---------------------------------------------------------------------------------------------------- | | `analyze_test_repo` | Analyzes a repository accessible to the configured service; confirm the data-access boundary. | | `migrate_repo_to_contextqa` | Parses supported tests and creates ContextQA cases. Supports a dry run. | | `export_to_playwright` | Returns a Playwright file manifest for selected cases; review and validate it before standalone use. | Migrated cases can use supported ContextQA execution capabilities, including [AI self-healing](/web-testing/self-healing.md). Review any maintenance change against the original assertion; a repaired locator does not establish that the business outcome remains correct. *** ## Step 1: Analyze your existing repository Start with analysis after confirming repository access. Compare the detected framework and file inventory with your checkout. Do not assume this tool runs on your machine or keeps source local simply because its input is a filesystem path. Ask your agent: ``` Analyze the test repository at /home/dev/projects/my-app/e2e and tell me what framework it uses and how many tests it contains. ``` The agent calls `analyze_test_repo` with your `repo_path` and returns: * `detectedFramework` — for example, `cypress`, `playwright`, `selenium`, or `jest`. * `language` — the language the tests are written in. * `testFiles` — the list of test files found. * `estimatedTestCount` — how many tests are migrated. **Verify it worked:** The agent reports the detected framework and a test count that matches your expectation. If the count looks low, confirm you pointed at the directory that actually contains the specs (for example, `cypress/e2e` or `tests/`) rather than the project root. {% hint style="info" %} **Detection ambiguous?** If a repo mixes frameworks or uses a non-standard layout, detection can guess wrong. You can override it in the next step by naming the framework explicitly. {% endhint %} *** ## Step 2: Preview the migration with a dry run Never migrate blind. Run the migration in dry-run mode first to see exactly how many test cases ContextQA creates and how many it skips — without changing anything in your workspace. Ask your agent: ``` Do a dry-run migration of /home/dev/projects/my-app/e2e into ContextQA. The app under test is https://staging.example.com. Show me how many tests will migrate and how many will be skipped. ``` The agent calls `migrate_repo_to_contextqa` with `dry_run` set to `true`. It returns: * `migratedCount` — the projected number of test cases. * `skippedCount` — tests that cannot be converted automatically. * A `summary` message describing the result. In dry-run mode, no test cases are created. Review the projected counts before continuing. If ContextQA detected the wrong framework in Step 1, override it by naming the framework in your prompt: ``` Do the same dry run, but treat the repo as a selenium project. ``` The agent passes your value in the `framework` parameter (`cypress`, `playwright`, `selenium`, or `jest`). **Verify it worked:** The agent reports a projected `migratedCount` close to the `estimatedTestCount` from Step 1. A large `skippedCount` usually means the suite relies on logic that does not map to test steps — see [Troubleshooting](#troubleshooting). *** ## Step 3: Run the migration Once the dry-run preview looks right, run the migration for real. Ask your agent: ``` The dry run looks good. Run the migration for real and give me the IDs of the test cases you create. ``` The agent calls `migrate_repo_to_contextqa` again with `dry_run` set to `false`. It returns: * `migratedCount` — the number of test cases created. * `skippedCount` — the number skipped. * `createdTestCaseIds` — the IDs of the new ContextQA test cases. * A `summary` message. **Verify it worked:** The agent returns a list of `createdTestCaseIds`. Open your ContextQA workspace and confirm the new test cases appear in the [test case list](/web-testing/creating-test-cases.md). Note the IDs — you use them in the next step. *** ## Step 4: Verify the migrated tests A migrated test case is a starting point, not a finished test. AI-inferred steps and assertions need a human review, so verify the migration by inspecting the steps and running at least one test case end to end. ### Review the steps Ask your agent: ``` Show me the steps for the test cases you just migrated. ``` The agent retrieves the step definitions. Read them the way you would review a pull request: * Confirm the natural-language steps capture what the original test did. * Check that assertions survived — every meaningful check in the original test should map to a verification step. Add any that were dropped in the [Test Steps Editor](/web-testing/test-steps-editor.md). * Replace hardcoded credentials or data with [environment](/execution/environments.md) parameters or a [test data profile](/web-testing/test-data-management.md). ### Run one test case Pick one migrated test and run it to confirm it executes against your application. ``` Run the migrated test case with ID 128 and tell me whether it passed. ``` The agent runs the test, polls for completion, and reports the result. If a step fails, ask for the root cause: ``` It failed. Get the root cause analysis and explain why. ``` **Verify it worked:** Retrieve the actual verdict and relevant step evidence for the same application build and fixture. Completion alone is not a pass, and a single passing case does not validate the entire migration. Investigate assertion, data, environment, and conversion differences before changing steps; treat AI root-cause output as a hypothesis to verify. *** ## Keep a two-way path (optional) An export can provide a code snapshot for parallel evaluation or handoff to a team that prefers scripts. Treat it as a point-in-time artifact, not as proof of live two-way synchronization or lossless round-trip conversion. Ask your agent: ``` Export only test cases 128, 129, and 130 as a Playwright project. Return the manifest and identify any manual or assumed-success steps. After review, save the files under my approved empty local directory. Do not print credentials or execute the project yet. ``` The current `export_to_playwright` tool accepts an explicit `test_case_ids` list and optional `project_name`. It returns `project_name`, `file_count`, `files` entries with relative `path` and `content`, and `summary`. The coding client saves these files through its own authorized filesystem capability; the hosted server does not write them to your laptop. Do not assume a `tsconfig.json` or a type-check setup is included. See [export and portability](/testing-with-ai-coding-agents/export-and-portability.md) for the complete review workflow. {% hint style="warning" %} Exported code does not automatically inherit later ContextQA changes, managed execution behavior, self-healing, or evidence storage. Exported values and configuration must be audited and do not recreate managed secret or test-data lifecycles. A successful export also does not prove that edited Playwright code can be re-imported without loss. Verify those boundaries in your workspace before making a portability claim. {% endhint %} ## Run a clean-environment portability test Use this exit test before a purchase or migration decision depends on portability. It asks whether a representative export can run outside the platform and makes every remaining dependency visible. ### Step 1: Select a representative export set Choose tests that expose the real ownership boundary: * one critical happy path with business assertions; * one negative or permission path; * one data-dependent workflow; * one workflow using environment parameters or credentials; * one failure that requires screenshots, logs, or traces; and * one test that previously needed maintenance or self-healing. Record the source test-case IDs, names, last-reviewed dates, and ContextQA run references before exporting. ### Step 2: Export to an empty directory Call `export_to_playwright` with explicit case IDs, inspect its returned manifest, and have the coding client save approved relative paths under an empty local directory. Reject absolute paths, traversal, or unexpected overwrites. Preserve the requested IDs, file count, file inventory, local save location, and actual project instructions. Inventory the result: | Item | Present? | File or evidence | Reviewer note | | ----------------------------------- | -------- | ---------------- | ------------- | | Package manifest | | | | | Playwright configuration | | | | | TypeScript configuration | | | | | One expected spec per selected test | | | | | Required assertions | | | | | Fixture or setup dependencies | | | | | Environment-variable names | | | | | Data setup and cleanup instructions | | | | | Browser/project configuration | | | | | Artifact configuration | | | | The current generator may emit plaintext credentials in `credentials.env`. Inspect the manifest privately before sharing or committing; move required values into the standalone runner's approved secret store. Also replace assumed-success AI verification, implement manual checkpoints, and restore branch and loop semantics before treating a green run as equivalent coverage. ### Step 3: Move to a clean runner Use a disposable machine, container, or CI job that: * has no ContextQA session or local cache; * has no access to the source workspace unless explicitly required; * installs dependencies from the exported manifest; * receives only documented environment values; and * can reach the same approved test environment. Record the operating system, runtime, package-manager version, browser installation step, dependency lockfile state, and exact command used. ### Step 4: Run normal and seeded-failure cases Run the exported tests against the same immutable application build used for the ContextQA comparison. Then run a reversible seeded failure in a disposable fixture. Verify: 1. The expected tests are discovered. 2. Required assertions execute rather than being skipped. 3. The normal fixture produces the expected results. 4. The seeded defect produces the expected failure. 5. Failure output is sufficient for the standalone team's debugging workflow. 6. Retries, timeouts, projects, and concurrency are explicit in the exported configuration or the residual-dependency register. ### Step 5: Record residual dependencies | Capability | Exported code | Recreated by your team | Remains managed | Missing or unknown | Owner | | ------------------------------------ | ------------- | ---------------------- | --------------- | ------------------ | ----- | | Test logic and assertions | | | | | | | Credentials and secrets | | | | | | | Seed data and cleanup | | | | | | | Browser infrastructure | | | | | | | Parallelism and queueing | | | | | | | Retry and timeout policy | | | | | | | Screenshots, video, logs, and traces | | | | | | | Result history and retention | | | | | | | Failure analysis | | | | | | | Self-healing or maintenance workflow | | | | | | | CI status and reviewer link | | | | | | Portability means the team understands and accepts this ownership transfer. It does not require every managed capability to appear in a code export. ### Step 6: Test the claimed round trip separately If re-importing edited Playwright code is a requirement, treat it as a separate acceptance test. Do not infer re-import from export. ``` Export reference: Standalone commit: Edited behavior and assertion: Supported re-import method: Re-import result: Behavior preserved: Assertions preserved: Unsupported constructs: Reviewer: ``` If no supported re-import path is documented or demonstrated, record `No verified round trip` and make the workflow one-way with an explicit source of truth. ### Portability decision record ``` Decision: Accept / Accept with dependencies / Remediate / Reject Representative test IDs: Export reference and date: Clean-runner definition: Normal-run result: Seeded-failure result: Residual dependencies: Verified re-import behavior, if required: Source of truth after migration: Exit owner: Evidence and approvers: ``` Use the [AI testing pilot scorecard](/evaluation-and-governance/ai-testing-pilot-scorecard.md) to combine this result with coverage, reliability, effort, and integration evidence. *** ## Verification You have completed the migration when: * [ ] `analyze_test_repo` detected your framework and a test count that matches the repo. * [ ] A dry run reported an acceptable `migratedCount` and `skippedCount`. * [ ] The real migration returned a list of `createdTestCaseIds`. * [ ] The new test cases appear in your ContextQA workspace. * [ ] At least one migrated test case runs to completion with a full evidence package. * [ ] If portability is a decision criterion, a representative export ran in a clean environment and residual dependencies were recorded. *** ## Troubleshooting | Symptom | Cause | Fix | | -------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Wrong framework detected | Mixed frameworks or a non-standard layout | Name the framework in your prompt so the agent sets the `framework` parameter (`cypress`, `playwright`, `selenium`, or `jest`). | | `estimatedTestCount` is 0 or too low | The path points at the project root, not the specs | Point `repo_path` at the directory that holds the test files, such as `cypress/e2e` or `tests/`. | | High `skippedCount` | Tests rely on conditional logic, loops, or custom code the parser cannot map to steps | Migrate what converts cleanly, then rebuild the complex cases using [custom code steps](/web-testing/custom-code-steps.md), [loops, and conditionals](/web-testing/test-steps-editor.md). | | Migrated steps miss an assertion | The original assertion had no clear natural-language equivalent | Add a verification step manually in the [Test Steps Editor](/web-testing/test-steps-editor.md). | | A migrated test fails on the first run | Hardcoded data, missing environment config, or a step that needs more detail | Attach an [environment](/execution/environments.md) or [test data profile](/web-testing/test-data-management.md), then use the [root cause analysis](/reporting/failure-analysis.md) to refine the failing step. | *** ## Summary You migrated an existing test suite into ContextQA: 1. **Analyzed** the repository to detect its framework and test count. 2. **Previewed** the migration with a dry run before changing anything. 3. **Migrated** the suite into a ContextQA workspace. 4. **Verified** the result by reviewing steps and running a test case. Your tests now run as natural-language ContextQA test cases with AI self-healing, and you can export them back to Playwright whenever you need to. ## Next steps * **Organize the migrated tests:** Group them into suites and plans so you can run them together. See [Managing Test Suites](/web-testing/managing-test-suites.md) and [Test Plans](/web-testing/test-plans.md). * **Harden data handling:** Replace hardcoded values across the suite with parameters. See [Test Data Management](/web-testing/test-data-management.md). * **Run in CI:** Trigger the migrated suite from your pipeline on every pull request. See [GitHub Actions](/integrations/github-actions.md), [Jenkins](/integrations/jenkins.md), or [GitLab CI](/integrations/gitlab-ci.md). * **Explore available tools:** Review the documented migration tools, then confirm exact names and parameters in the connected manifest. See [Support-to-Fix & Migration Platform Tools](/mcp-server/tool-reference/support-and-migration.md). ## Related pages * [Tutorial: Create your first test with an AI agent](/mcp-server/first-test-tutorial.md) — connect the MCP server and run your first agent-driven test * [Migration Overview](/migrate-to-contextqa/migration.md) — choose the direct-analysis, intermediate-export, or intent-led path * [Migration Planning & Acceptance Checklist](/migrate-to-contextqa/planning-checklist.md) — reconcile scope, assertions, evidence, overlap, and rollback * [Support-to-Fix & Migration Platform Tools](/mcp-server/tool-reference/support-and-migration.md) — full parameter reference for `analyze_test_repo`, `migrate_repo_to_contextqa`, and `export_to_playwright` * [AI Self-Healing](/web-testing/self-healing.md) — why intent-based steps survive UI changes * [Creating Test Cases](/web-testing/creating-test-cases.md) — how ContextQA test cases are structured * [Agent Integration Guide](/mcp-server/agent-integration-guide.md) — tool ordering and multi-step orchestration {% hint style="info" %} **Assess a representative migration before moving the full suite.** [**Book a Demo →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=test_suite_migration) to see a migration with your own repository. {% 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/migrating-existing-tests.md?ask=&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.