> 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/mcp-server/migrating-existing-tests.md). # How to Migrate an Existing Test Suite {% 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 %} This guide walks you through migrating an existing test repository into ContextQA. You point an AI agent at your local repo, ContextQA detects the framework, converts each test into a natural-language ContextQA test case, and you verify the results. You keep an escape hatch too: ContextQA can export your migrated tests back to Playwright TypeScript at any time. 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 on the same machine as your AI agent. ContextQA detects Selenium, Cypress, Playwright, and Jest projects. * 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" %} **Local path required.** The analysis and migration tools read files from the local filesystem, so run your AI agent on the same machine where the repository is checked out. Have the absolute path ready, for example `/home/dev/projects/my-app/e2e`. {% endhint %} *** ## How migration works ContextQA does not run your existing test code. Instead, it parses each test file, extracts the intent of every action and assertion, and creates an equivalent ContextQA test case authored in natural language. Three MCP tools cover the full path: | Tool | Purpose | | --------------------------- | --------------------------------------------------------------------------------------------------------------- | | `analyze_test_repo` | Detects the framework, lists test files, and estimates the test count. Local only — sends nothing to ContextQA. | | `migrate_repo_to_contextqa` | Parses the tests and creates equivalent ContextQA test cases. Supports a dry run. | | `export_to_playwright` | Exports ContextQA test cases back to a runnable Playwright TypeScript project. | Because migrated tests become natural-language test cases, they gain ContextQA's [AI self-healing](/web-testing/self-healing.md) — brittle CSS and XPath selectors are replaced by intent-based steps that survive UI changes. *** ## Step 1: Analyze your existing repository Start with a read-only analysis. This tells you which framework ContextQA detected and how many tests it found, so there are no surprises during migration. This step runs entirely on your machine and sends no data to ContextQA. 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:** At least one migrated test case runs to completion and produces an evidence package — per-step screenshots, a video recording, and logs. A failure here is often a step that needs data or a small wording adjustment, not a broken migration. Use the root cause analysis to pinpoint it. *** ## Keep a two-way path (optional) Migration is not a one-way door. To keep running Playwright in parallel — or hand code back to a team that prefers scripts — export your ContextQA test cases to a complete Playwright TypeScript project. Ask your agent: ``` Export test cases 128, 129, and 130 to a Playwright project at /home/dev/projects/playwright-export. ``` The agent calls `export_to_playwright` and writes a full project — `playwright.config.ts`, `package.json`, `tsconfig.json`, and one spec file per test case — to the output directory. It returns the `outputPath`, an `exportedCount`, the list of `specFiles`, and a suggested `run_command` such as `npx playwright test`. Omit the IDs to export every test case in the workspace. *** ## 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. *** ## 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 every tool:** Browse the full parameter reference for the migration tools and all 67 tools. 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 * [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" %} **Move your suite to self-healing tests — no rewrite required.** [**Start Free Trial →**](https://app.contextqa.com/register) — Or [**Book a Demo →**](https://contextqa.com/book-a-demo/) 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://learning.contextqa.com/mcp-server/migrating-existing-tests.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.