> 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/playwright-to-contextqa.md).

# 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](/migrate-to-contextqa/migrating-existing-tests.md) 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](https://playwright.dev/docs/test-projects) and [trace viewer](https://playwright.dev/docs/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](https://playwright.dev/docs/test-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](/execution/environments.md)                 | 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](/web-testing/test-data-management.md) | 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](/web-testing/test-steps-editor.md).
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](/migrate-to-contextqa/migrating-existing-tests.md#run-a-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

<details>

<summary>The analyzer found the specs but missed important behavior</summary>

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.

</details>

<details>

<summary>One Playwright test becomes too large in ContextQA</summary>

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.

</details>

<details>

<summary>The source uses projects for environments and browsers</summary>

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.

</details>

## Related documentation

* [Migration overview](/migrate-to-contextqa/migration.md)
* [Migration planning checklist](/migrate-to-contextqa/planning-checklist.md)
* [MCP-assisted suite migration](/migrate-to-contextqa/migrating-existing-tests.md)
* [Test Plans](/web-testing/test-plans.md)
* [Test data management](/web-testing/test-data-management.md)

{% hint style="info" %}
**Want to evaluate your Playwright migration with one real fixture-heavy test?** [**Book a migration review →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=playwright_migration) — Bring the spec, its fixtures, and the last failure trace so the conversion can be judged on evidence.
{% 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/playwright-to-contextqa.md?ask=<question>&goal=<user_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.