> 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/planning-checklist.md).

# Planning & Acceptance Checklist

Inventory source tests, preserve assertions and dependencies, compare parallel runs, control cutover, and document rollback for a ContextQA migration.

## Quick answer

Before converting tests, reconcile the source inventory, classify dependencies, select a representative pilot, and define assertion, failure, evidence, effort, and rollback gates. Migrate in waves, never from an unreviewed bulk import. Every source asset needs a final disposition—migrated, retained, replaced by another control, or retired with approval—and every release-critical ContextQA test needs a normal run plus a controlled failure that proves its assertion can fail.

## Copy the migration charter

```
Decision:
Source platform/framework and version:
Source repository/workspace:
ContextQA workspace:
Business owner:
Migration owner:
Technical reviewers:
Security/release reviewers:
In-scope applications and environments:
Out-of-scope tests and why:
Pilot cohort:
Target overlap window:
Required evidence:
Acceptance gates:
Rollback trigger and owner:
Decision date:
```

Keep the charter versioned. If scope changes, add a dated decision rather than replacing the original baseline silently.

## Phase 1: Inventory the source

### Suite-level inventory

| Suite | Purpose | Test count | Release critical? | Normal schedule | Owner | Last meaningful run | Disposition                     |
| ----- | ------- | ---------: | ----------------- | --------------- | ----- | ------------------- | ------------------------------- |
|       |         |            |                   |                 |       |                     | Pilot / Later / Retain / Review |

### Test-level inventory

| Source ID/path | Behavior | Assertions | Data/fixture | Environment | Browser/device | Dependencies | Last result | Proposed disposition |
| -------------- | -------- | ---------- | ------------ | ----------- | -------------- | ------------ | ----------- | -------------------- |
|                |          |            |              |             |                |              |             |                      |

Look beyond test files. Inventory:

* page objects, screen abstractions, reusable modules, fixtures, hooks, and helper libraries;
* setup and teardown jobs;
* environment files and secret references;
* data factories, database tasks, API setup, email/SMS inboxes, and file fixtures;
* browser projects, grids, mobile devices, proxies, tunnels, certificates, and locales;
* CI triggers, retry policies, sharding, concurrency, and required-check names;
* screenshots, videos, logs, traces, reports, retention, and audit exports; and
* requirement, defect, and test-management links.

### Reconciliation equation

Use counts only as a completeness control:

```
source inventory = migrated + retained + replaced + retired + unresolved
```

The equation should balance for each migration wave. A balanced count does not prove coverage; the assertion review does.

## Phase 2: Classify conversion difficulty

| Class                  | Typical characteristics                                                        | Treatment                                               |
| ---------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
| A — direct             | Linear UI flow, explicit assertions, simple data                               | Analyze/import, review, run                             |
| B — structured         | Reusable helpers, parameters, setup/cleanup, multiple projects                 | Map dependencies and rebuild supporting configuration   |
| C — custom             | Code, loops, conditionals, downloads, visual checks, external services         | Create a design note and prove feasibility individually |
| D — proprietary        | Model-based objects, binary/source-vendor format, undisclosed runtime behavior | Intent-led reconstruction or retain source control      |
| E — obsolete/duplicate | No current requirement, never runs, duplicates another control                 | Retire only with owner approval                         |

Select the pilot across A through D. A pilot containing only Class A cannot validate the broader migration.

## Phase 3: Define behavior packets

Create one packet per business behavior:

| Field                      | Required content                                     |
| -------------------------- | ---------------------------------------------------- |
| Behavior ID                | Stable migration identifier                          |
| Business risk              | What could go wrong for a user or system             |
| Source references          | Test IDs/paths and revision                          |
| Preconditions              | Role, tenant, records, feature flags, build          |
| Actions                    | User or system behavior, not source-framework syntax |
| Positive assertions        | Expected successful outcomes                         |
| Negative assertions        | Disallowed or error behavior                         |
| Persisted-state assertions | API/database/next-page evidence when required        |
| Data lifecycle             | Create, isolate, reset, and cleanup                  |
| Environment matrix         | Browser/device/network/locale requirements           |
| Evidence                   | Source and ContextQA run/artifact references         |
| Limitations                | Unsupported or intentionally excluded behavior       |
| Owner/reviewer             | Accountable people                                   |

This packet prevents a migration from turning an assertion-rich test into a sequence of clicks.

## Phase 4: Prepare the ContextQA destination

* [ ] Workspace and role permissions are approved.
* [ ] Environments point to the correct nonproduction application builds.
* [ ] Secrets use approved password/vault variables rather than literal steps.
* [ ] Test data profiles are scoped and resettable.
* [ ] Proxy or remote-browser profiles are tested when required.
* [ ] Test suites group one release purpose rather than source folders mechanically.
* [ ] Test plans define the required browser/device and execution settings.
* [ ] Evidence access and retention meet reviewer needs.
* [ ] A dedicated migration label/folder identifies unaccepted tests.

Do not let imported tests enter a required CI gate until their acceptance record is complete.

## Phase 5: Convert a representative pilot

For supported repositories, follow [MCP-assisted migration](/migrate-to-contextqa/migrating-existing-tests.md): analyze, dry run, inspect skipped items, migrate, and review. For unsupported platforms, follow the relevant [Tosca](/migrate-to-contextqa/tricentis-tosca-to-contextqa.md) or [mabl](/migrate-to-contextqa/mabl-to-contextqa.md) staged path.

Use a pilot cohort containing:

* a release-critical happy path;
* a negative permission or validation case;
* parameterized data;
* a reusable setup or authentication dependency;
* a custom integration or file operation;
* at least two required browsers/devices if applicable;
* a historically flaky or maintenance-heavy test; and
* a failure that needs diagnostic evidence.

## Phase 6: Review assertion integrity

| Behavior ID | Source assertion | ContextQA assertion | Positive/negative/boundary | Reviewer | Gap/disposition |
| ----------- | ---------------- | ------------------- | -------------------------- | -------- | --------------- |
|             |                  |                     |                            |          |                 |

Reject the migrated case when:

* an assertion became a navigation step;
* a denied action is verified only by the absence of an error;
* a persisted-state expectation is checked only visually;
* an unexpected skip can still produce a pass;
* data setup makes the assertion vacuously true; or
* a broad visual judgment replaces an exact financial, security, or data-integrity check.

## Phase 7: Prove the test can fail

For each critical behavior:

1. Run the ContextQA test against the known-good immutable build.
2. Record the run and expected passing assertions.
3. Introduce one reversible defect in a disposable fixture or branch.
4. Run the same test and configuration.
5. Verify that the intended assertion fails for the intended reason.
6. Restore the fixture and rerun.

| Behavior | Good-build run | Seed commit | Expected failure | Observed failure | Restored run | Reviewer |
| -------- | -------------- | ----------- | ---------------- | ---------------- | ------------ | -------- |
|          |                |             |                  |                  |              |          |

Never seed a defect in production or a shared environment without explicit coordination.

## Phase 8: Compare source and ContextQA in parallel

Run the same behavior packet against the same application build and data revision.

| Build | Behavior | Source outcome | ContextQA outcome | Evidence complete? | Human minutes | Difference classification                     | Owner |
| ----- | -------- | -------------- | ----------------- | ------------------ | ------------: | --------------------------------------------- | ----- |
|       |          |                |                   |                    |               | Product / Test / Data / Environment / Unknown |       |

Classify every divergence. Do not discard a difference because the preferred tool passed.

Measure:

* test creation and migration review time;
* routine execution and queue time;
* false passes and false failures under the agreed protocol;
* failure-triage time;
* maintenance intervention;
* incomplete, canceled, timed-out, and retried runs; and
* evidence availability to the release reviewer.

## Phase 9: Decide each source test’s disposition

| Disposition | Definition                                                        | Required approval                                  |
| ----------- | ----------------------------------------------------------------- | -------------------------------------------------- |
| Migrated    | Accepted ContextQA behavior packet replaces the source control    | Test owner and release owner for critical coverage |
| Retained    | Source test remains authoritative for a named requirement         | Test owner                                         |
| Replaced    | Another control owns the behavior                                 | Owners of both controls                            |
| Retired     | Requirement is obsolete, duplicative, or no longer worth the cost | Business/test owner with rationale                 |
| Unresolved  | Decision lacks evidence                                           | Migration owner and due date; no silent cutover    |

## Phase 10: Cut over with rollback

Before cutover:

* [ ] Source tests and configuration remain versioned and runnable.
* [ ] Source credentials remain valid through the rollback window.
* [ ] ContextQA plans have stable owners and names.
* [ ] CI state mapping passed the [acceptance runbook](/evaluation-and-governance/ci-integration-acceptance-runbook.md).
* [ ] Required-check or schedule changes are reviewed separately.
* [ ] On-call and support routes know which system is authoritative.
* [ ] Rollback has been tested on a disposable branch/environment.
* [ ] Old and new evidence is retained for the overlap period.

Rollback triggers can include:

* an unexplained false pass in a critical behavior;
* missing evidence during a release;
* repeated queue/execution behavior outside the accepted threshold;
* environment or network incompatibility;
* critical test data contamination; or
* an unresolved authentication or authorization regression.

## Migration acceptance record

```
Wave:
Source count:
Migrated:
Retained:
Replaced:
Retired:
Unresolved:

Critical assertion review:
Seeded-failure results:
Parallel-run cohort:
Divergences and dispositions:
Human effort:
Known limitations:
Rollback test:
Portability result:

Decision: Accept / Remediate / Narrow / Stop
Approvers:
Next review:
```

## Related documentation

* [Migration overview](/migrate-to-contextqa/migration.md)
* [Playwright migration](/migrate-to-contextqa/playwright-to-contextqa.md)
* [Selenium migration](/migrate-to-contextqa/selenium-to-contextqa.md)
* [Tricentis Tosca migration](/migrate-to-contextqa/tricentis-tosca-to-contextqa.md)
* [mabl migration](/migrate-to-contextqa/mabl-to-contextqa.md)

{% hint style="info" %}
**Need a migration plan sized to your suite?** [**Book a migration planning session →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=migration_planning_checklist) — Bring your suite inventory and two difficult tests; we will help classify the pilot and evidence gates.
{% 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/planning-checklist.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.