Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

How to Migrate an Existing Test Suite

Migrate an existing Selenium, Cypress, or Playwright test repository into ContextQA using an AI agent and the MCP migration tools — analyze the repo, preview with a dry run, migrate, and verify the re

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.

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

  • The MCP server connected to your AI assistant. If you have not done this, complete Tutorial: Create your first test with an AI agent 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 — specifically test cases, steps, and workspaces.

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.

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 — 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:

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.

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.

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:

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:

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.

Step 3: Run the migration

Once the dry-run preview looks right, run the migration for real.

Ask your agent:

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

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.

  • Replace hardcoded credentials or data with environment parameters or a test data profile.

Run one test case

Pick one migrated test and run it to confirm it executes against your application.

The agent runs the test, polls for completion, and reports the result. If a step fails, ask for the root cause:

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:

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:

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, loops, and conditionals.

Migrated steps miss an assertion

The original assertion had no clear natural-language equivalent

Add a verification step manually in the Test Steps Editor.

A migrated test fails on the first run

Hardcoded data, missing environment config, or a step that needs more detail

Attach an environment or test data profile, then use the root cause analysis 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

Related pages

Move your suite to self-healing tests — no rewrite required. Start Free Trial → — Or Book a Demo → to see a migration with your own repository.

PreviousTutorial: Your First Test with an AI AgentNextAgent Integration Guide

Last updated

Was this helpful?