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

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.

Start with the source-neutral Migration Overview. 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.

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).
• 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 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 — specifically test cases, steps, and workspaces.

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.

---

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

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:

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.

---

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

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 for the complete review workflow.

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.

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 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, 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

• Organize the migrated tests: Group them into suites and plans so you can run them together. See Managing Test Suites and Test Plans.
• Harden data handling: Replace hardcoded values across the suite with parameters. See Test Data Management.
• Run in CI: Trigger the migrated suite from your pipeline on every pull request. See GitHub Actions, Jenkins, or GitLab CI.
• 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.

Related pages

• Tutorial: Create your first test with an AI agent — connect the MCP server and run your first agent-driven test
• Migration Overview — choose the direct-analysis, intermediate-export, or intent-led path
• Migration Planning & Acceptance Checklist — reconcile scope, assertions, evidence, overlap, and rollback
• Support-to-Fix & Migration Platform Tools — full parameter reference for analyze_test_repo, migrate_repo_to_contextqa, and export_to_playwright
• AI Self-Healing — why intent-based steps survive UI changes
• Creating Test Cases — how ContextQA test cases are structured
• Agent Integration Guide — tool ordering and multi-step orchestration

Assess a representative migration before moving the full suite. Book a Demo → to see a migration with your own repository.