Migrate from Playwright

Analyze a Playwright repository, map fixtures and projects, migrate a representative slice, verify assertions and failures, and cut over safely to ContextQA.

Quick answer

Start with the Playwright repository as a versioned source, run ContextQA’s documented MCP analysis and dry run, and review the skipped-test list before creating cases. Map every Playwright project, fixture, helper, authentication state, data dependency, and assertion to a ContextQA destination or an explicitly retained control. Migrate a representative slice first, run it against the same build, prove a seeded defect fails, and keep both paths active until behavior and evidence parity are accepted.

When this path applies

Use this guide for a repository built on @playwright/test. If you use Playwright only as a library inside another runner, inventory the surrounding framework separately.

ContextQA’s current MCP migration workflow documents Playwright repository analysis, dry-run migration, test creation, and Playwright export. The migration still requires technical review: repository detection cannot decide which project, fixture, retry, or helper behavior is part of your release contract.

Preserve a reproducible baseline

Before migration, record:

Repository URL:
Commit SHA:
Node.js version:
Package manager and lockfile:
Playwright version:
playwright.config path:
Test directories:
Default command:
Required projects:
CI command and environment:
Baseline run/report/trace:
Migration owner:

Run the source suite at that commit. Preserve the HTML/JUnit report your team uses and at least one diagnostic trace for a representative failure. Playwright recommends configuration through projects and supports trace recording modes such as first retry or retain on failure; record the actual settings instead of assuming defaults. See the official Playwright projects and trace viewer documentation.

Inventory Playwright semantics

Projects and execution matrix

Playwright project	Browser/device	Base URL/environment	Auth state	Retries	Dependencies	ContextQA destination
						Test plan machine / retained / review

Do not treat a project as only a browser name. Projects can encode environments, authenticated states, dependencies, timeouts, and test filters.

Fixtures and hooks

Playwright fixtures are isolated, reusable setup objects with explicit setup and teardown lifecycles. Map each one:

Fixture/hook	Scope	Creates or changes	Cleanup	Secret/data dependency	ContextQA mapping	Owner
	Test / worker / global				Environment / data profile / API setup / custom step / retained

Review:

• built-in page, context, and request use;
• custom test- and worker-scoped fixtures;
• project dependencies and setup projects;
• beforeAll, beforeEach, afterEach, and afterAll hooks;
• storageState and authenticated-session creation;
• API-based data setup and cleanup; and
• attached diagnostics or custom reporters.

Use the official Playwright fixtures behavior as the source reference.

Helpers and page objects

Helper/page object	Business intent	Hidden waits/data/assertions	Used by	Migration treatment
				Express as steps / parameterize / custom code / retain

A page-object method named submitOrder() may contain navigation, retry logic, API waits, and assertions. Read its implementation before translating it to one natural-language step.

Assertions

Source test	Playwright assertion	Risk protected	ContextQA assertion	Review status

Pay special attention to:

• web-first assertions with automatic retry;
• soft assertions;
• API response and persisted-state checks;
• download, file, email, visual, or accessibility assertions;
• custom matchers; and
• assertions inside helpers or fixtures rather than the spec file.

Step 1: Analyze the repository

Connect an approved MCP client, then ask it to analyze the exact checked-out path:

Analyze the Playwright test repository at <absolute repo path>.
Do not migrate anything. Report the detected framework, test count,
configuration files, fixtures/helpers found, unsupported patterns, and files
that were not analyzed. Use repository commit <full SHA> in the report.

Compare the reported count with the source inventory. Investigate a zero or unexpectedly low count before proceeding.

Step 2: Run a dry migration

Preview migration of the representative Playwright tests under <path> to
ContextQA workspace <workspace reference>. Use dry-run mode. Return the
candidate test names, migrated/skipped counts, skip reasons, and no other
workspace changes.

Select tests across simple, fixture-heavy, parameterized, negative, custom-code, and multi-project cases. A dry run that skips every difficult test has not validated the migration.

Step 3: Map configuration before creating tests

Playwright source	ContextQA destination	Acceptance question
baseURL or environment project	Environment	Does the plan reach the same immutable build?
Environment variables/secrets	Password/vault or approved secret control	Are literal values absent from steps and logs?
Test parameters	Test data profile	Are rows isolated and resettable?
Browser/device project	Test-plan machine	Is the required matrix observed?
Setup/API fixture	API step, prerequisite case, custom code, or retained job	Does setup fail visibly and clean up?
Proxy/grid endpoint	Proxy or remote-browser profile	Has connection and ownership been tested?
Retry/timeout	Plan/case settings and release policy	Are initial and final outcomes visible?
Reporter/artifacts	ContextQA results plus retained external output	Can intended reviewers access equivalent evidence?

Create the destination configuration before migrating tests that depend on it.

Step 4: Migrate the pilot slice

Run the real migration for only the accepted pilot files or directory. Preserve the returned created-test references and skipped-test reasons.

After creation:

1. Open every migrated test in the test steps editor.
2. Compare the steps with the source behavior packet.
3. Re-add or rewrite missing assertions.
4. Replace hardcoded data with approved environment or test-data references.
5. Split tests that contain unrelated behaviors.
6. Mark each test Accepted, Needs remediation, or Retain in Playwright in the migration ledger.

Step 5: Verify behavior, not syntax

Run the Playwright source and ContextQA candidate against the same application build and data revision.

Behavior	Playwright project/result	ContextQA plan/result	Assertion parity	Evidence parity	Difference owner

Differences may be legitimate—for example, ContextQA may represent intent rather than locators—but the protected outcome must remain equivalent.

Step 6: Run negative controls

Use a disposable fixture or branch:

1. Change one asserted business outcome.
2. Run the unchanged Playwright test and ContextQA test.
3. Confirm both fail for the expected reason.
4. Check that neither test was skipped or passed after weakening an assertion.
5. Restore the application and confirm both pass again.

Also test a setup failure, wrong environment, and timeout for at least one release-critical workflow.

Step 7: Decide coexistence and source of truth

Pattern	Use when	Control
ContextQA authoritative	Accepted coverage moves to managed tests	Freeze/remove source case only after overlap
Playwright authoritative	Code review and repository ownership remain required	ContextQA copy is evaluation-only or generated from an explicit process
Split ownership	Different environments or test classes fit different systems	Label each behavior packet’s authoritative control
Temporary dual run	Migration evidence is still accumulating	Time-box overlap and classify divergences

There is no automatic live synchronization between independently maintained copies. If you export ContextQA tests back to Playwright, treat the result as a snapshot and run the clean-environment portability test.

Playwright migration checklist

• Repository, commit, runtime, package manager, and Playwright version are recorded.
• Source suite runs and its baseline report is preserved.
• Projects, fixtures, hooks, helpers, setup, and reporters are inventoried.
• Critical assertions—including those hidden in helpers—are mapped.
• Analysis count reconciles to the source inventory.
• Dry-run migrated/skipped counts and reasons were reviewed.
• Destination environment, data, credentials, and browser matrix exist.
• A representative pilot was migrated, not only easy happy paths.
• Normal and seeded-failure runs preserve assertion behavior.
• Skips, retries, timeouts, and setup failures remain visible.
• Parallel-run divergences are classified and owned.
• Authoritative source and rollback conditions are documented.

Common migration traps

The analyzer found the specs but missed important behavior

Inspect fixtures, helper libraries, page objects, and custom matchers. Much of a Playwright test’s setup or assertion behavior can live outside the spec file. Add it to the behavior packet and destination mapping explicitly.

One Playwright test becomes too large in ContextQA

Split it by business behavior while preserving shared setup through test data, environment configuration, or an approved reusable pattern. Keep requirement traceability across the split.

The source uses projects for environments and browsers

Create an explicit matrix. Map browser/device settings to test-plan machines and deployment values to ContextQA environments. Do not flatten both meanings into one label.

Related documentation

• Migration overview
• Migration planning checklist
• MCP-assisted suite migration
• Test Plans
• Test data management

Want to evaluate your Playwright migration with one real fixture-heavy test? Book a migration review → — Bring the spec, its fixtures, and the last failure trace so the conversion can be judged on evidence.