> 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/evaluation-and-governance/browser-grid-migration-checklist.md).

# Browser-Grid Migration Checklist

Compare required and observed browser execution, concurrency, network access, artifacts, ownership, overlap, and rollback before changing a browser grid.

## Quick answer

Do not migrate from a browser grid by counting browser names. Inventory the exact operating-system, browser, version, viewport, device, network, concurrency, artifact, and retention requirements behind today’s release decisions. Run representative ContextQA plans, record what was directly observed, and classify every requirement as native, externally connected, retained elsewhere, missing, or unknown. Keep an overlap period and a tested rollback path until critical coverage and evidence gates pass.

## What this guide does—and does not claim

This checklist helps a team evaluate whether ContextQA can replace part of a browser-grid workflow, coexist with it, or leave it unchanged.

ContextQA documentation describes:

* saved test-plan machines for browser or device execution;
* Chrome, Firefox, and Safari choices in the current cross-browser workflow;
* parallel execution subject to workspace capacity;
* execution evidence such as results, screenshots, video, and logs; and
* organization-level remote-browser profiles using an approved WebSocket endpoint.

It does **not** follow that every third-party grid feature, browser version, device, regional route, tunnel, or retention policy is automatically equivalent. A saved remote-browser profile is evidence that a connection can be configured; it is not proof that the full grid requirement is satisfied.

{% hint style="warning" %}
Do not describe ContextQA as directly executing on BrowserStack, Sauce Labs, or another named service unless that exact connection and workflow have been verified in your workspace. Record the observed endpoint, ownership, and result instead.
{% endhint %}

## Choose the migration pattern

```mermaid
flowchart TD
    A[Inventory required coverage] --> B[Run representative ContextQA plans]
    B --> C{All critical requirements observed?}
    C -- Yes --> D[Time-boxed replacement pilot]
    C -- Some --> E[Hybrid ownership]
    C -- No --> F[Retain current grid]
    D --> G[Overlap and rollback test]
    E --> G
    G --> H{Acceptance gates pass?}
    H -- Yes --> I[Approve bounded migration]
    H -- No --> J[Rollback or revise scope]
```

Use one of three explicit patterns:

| Pattern | When it fits                                                                                         | Main risk                                         |
| ------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Replace | ContextQA has directly demonstrated all critical requirements                                        | Hidden edge coverage is discovered after shutdown |
| Hybrid  | ContextQA covers primary flows; another grid owns special versions, devices, regions, or diagnostics | Duplicate runs and unclear failure ownership      |
| Retain  | Critical requirements are unavailable, unknown, or uneconomical to migrate                           | Evaluation effort without operational change      |

“Hybrid” is a real architecture, not a failed replacement. It can be the best outcome when specialized coverage has a clear owner.

## Step 1: Reconstruct the real requirement

Start from release policy, defect history, contracts, and actual usage—not from the grid vendor’s entire catalog.

### Browser and device inventory

| Requirement ID | User or contract source | OS/device | Browser and version | Viewport | Priority                       | Current owner |
| -------------- | ----------------------- | --------- | ------------------- | -------- | ------------------------------ | ------------- |
|                |                         |           |                     |          | Critical / Required / Optional |               |

Include:

* current stable versions and any pinned older versions;
* desktop and mobile viewport behavior;
* real-device requirements versus browser emulation;
* locale, timezone, geolocation, and accessibility settings;
* downloads, uploads, camera, microphone, or other hardware-dependent flows; and
* extension, certificate, or enterprise-policy dependencies.

### Execution and network inventory

| Requirement            | Current behavior | Required threshold | Why it matters                         |
| ---------------------- | ---------------- | ------------------ | -------------------------------------- |
| Concurrency            |                  |                    | Pull-request latency or nightly window |
| Queue time             |                  |                    | Developer feedback time                |
| Private-network access |                  |                    | Test environment reachability          |
| Approved egress region |                  |                    | Data or security policy                |
| Proxy/tunnel ownership |                  |                    | Incident response                      |
| Session isolation      |                  |                    | Data contamination risk                |
| Retry behavior         |                  |                    | Flake versus defect interpretation     |
| Maximum execution time |                  |                    | Pipeline timeout budget                |

### Evidence and retention inventory

| Artifact        | Required on pass? | Required on failure? | Retention | Access roles | Export need |
| --------------- | ----------------- | -------------------- | --------- | ------------ | ----------- |
| Step result     |                   |                      |           |              |             |
| Screenshot      |                   |                      |           |              |             |
| Session video   |                   |                      |           |              |             |
| Console log     |                   |                      |           |              |             |
| Network log     |                   |                      |           |              |             |
| Execution trace |                   |                      |           |              |             |
| CI summary      |                   |                      |           |              |             |

An artifact that exists but cannot be retained, exported, or opened by the reviewer may not meet the requirement.

## Step 2: Build the required-versus-observed matrix

Run a representative [cross-browser test plan](/execution/cross-browser-testing.md) and record observation, not expectation.

Use these dispositions:

* **Native:** demonstrated through the saved ContextQA workflow.
* **External connection:** demonstrated through an approved remote-browser profile; name the external owner.
* **Retained elsewhere:** intentionally remains in the current grid or another control.
* **Missing:** tested and unavailable for the evaluated configuration.
* **Unknown:** not yet tested or evidence was insufficient.

| Requirement ID | Required | Observed configuration | Disposition | Run/evidence reference | Owner | Decision |
| -------------- | -------- | ---------------------- | ----------- | ---------------------- | ----- | -------- |
|                |          |                        |             |                        |       |          |

Do not use a documentation page as the only evidence for a critical row. Link the actual test plan, run, artifact, or connection-test record.

## Step 3: Exercise network and remote-browser boundaries

If the application requires private access, first decide whether the route belongs at the application network, a proxy, or a remote browser endpoint.

For a ContextQA organization profile:

1. Create the narrowest approved [proxy or remote-browser profile](/execution/proxy-and-remote-browser-profiles.md).
2. Use a dedicated credential with the minimum required access.
3. Run **Test Connection** for a remote-browser profile.
4. Assign the profile to one disposable test case or plan.
5. Run a non-destructive smoke test.
6. Verify DNS, TLS, authentication, application reachability, and artifact availability.
7. Rotate or remove the pilot credential after testing when policy requires it.

Record which party owns:

* endpoint availability;
* browser images and versions;
* concurrency limits;
* network allowlists;
* credential rotation;
* session artifacts; and
* support escalation.

## Step 4: Measure concurrency without hiding queue time

Total feedback time has at least three parts:

```
feedback time = queue time + execution time + evidence/triage time
```

Run the same representative plan at normal and busy periods. Capture:

| Run | Requested concurrency | Started concurrency | Queue time | Execution time | Incomplete runs | Notes |
| --- | --------------------: | ------------------: | ---------: | -------------: | --------------: | ----- |
|     |                       |                     |            |                |                 |       |

Do not extrapolate from a single quiet run. If the workspace limit or external grid controls concurrency, name that boundary.

## Step 5: Compare diagnostic usefulness

Seed controlled failures in a disposable fixture:

1. Browser-specific layout or interaction failure.
2. JavaScript console error.
3. Failed or delayed network request.
4. Authentication or certificate failure in a test environment.
5. Intentional timeout.

For each failure, ask a reviewer who did not create the seed to diagnose it from the available artifacts.

| Seed | Expected signal | ContextQA evidence | Current-grid evidence | Reviewer diagnosis | Triage minutes | Gap |
| ---- | --------------- | ------------------ | --------------------- | ------------------ | -------------: | --- |
|      |                 |                    |                       |                    |                |     |

The winner is not necessarily the system with more artifacts. It is the system that preserves the identity and evidence needed for the team to make the next decision.

## Step 6: Design the overlap period

Use a fixed cohort and duration. A reasonable overlap definition includes:

```
Start date:
End date:
Application builds in scope:
Critical scenario IDs:
Browser/device matrix:
Current-grid job:
ContextQA plan:
Comparison owner:
Maximum allowed unexplained divergence:
```

During overlap, record divergences rather than choosing the preferred result:

| Build | Scenario | Current grid             | ContextQA                | Expected | Classification                                    | Owner |
| ----- | -------- | ------------------------ | ------------------------ | -------- | ------------------------------------------------- | ----- |
|       |          | Pass / Fail / Incomplete | Pass / Fail / Incomplete |          | Product / Test / Environment / Coverage / Unknown |       |

Review false passes before false failures: a noisy gate is painful, but an undetected critical defect defeats the release control.

## Step 7: Prepare rollback before cutover

The rollback plan should work without recreating deleted configuration.

| Rollback item                | Required state before cutover                   |
| ---------------------------- | ----------------------------------------------- |
| Current-grid workflow        | Preserved and runnable                          |
| Secrets and service accounts | Valid through the rollback window               |
| Test repository and config   | Versioned at a known commit                     |
| CI required-check change     | Reversible by an authorized owner               |
| Artifact access              | Retained for comparison                         |
| Escalation contact           | Named for both execution paths                  |
| Rollback drill               | Completed on a disposable branch or environment |

Trigger rollback when a critical requirement becomes missing, an unexplained false pass occurs, evidence is inaccessible during a release, or queue/execution behavior exceeds the accepted threshold repeatedly.

## Acceptance checklist

* [ ] The required browser/device/version matrix comes from user, contract, and defect evidence.
* [ ] Every critical row has an observed run or an explicit retained owner.
* [ ] Network access and credentials passed a non-destructive smoke test.
* [ ] Concurrency, queue time, and incomplete-run behavior were measured.
* [ ] Required artifacts are accessible to the intended reviewer and meet retention needs.
* [ ] Seeded browser, network, and timeout failures produced useful evidence.
* [ ] Hybrid responsibilities are named; no requirement is owned by “both teams.”
* [ ] The overlap cohort completed with divergences classified.
* [ ] The old path remains runnable through the rollback window.
* [ ] The rollback drill and approval record are complete.

## Decision record

```
Decision: Replace / Hybrid / Retain / Extend evaluation
Approved scope:
Excluded scope and owner:
Critical requirements passed:
Missing or unknown requirements:
Overlap result:
Rollback trigger and owner:
Evidence packet:
Approvers:
Review date:
```

## Common questions

<details>

<summary>Does a successful remote-browser connection prove grid compatibility?</summary>

No. It proves that the tested endpoint and credentials connected at that moment. Run the required browser, network, concurrency, and artifact scenarios before making a migration claim.

</details>

<details>

<summary>Should we retire the current grid after the first passing ContextQA plan?</summary>

No. Complete the required-versus-observed matrix, seeded-failure review, overlap cohort, and rollback drill first.

</details>

<details>

<summary>What if only specialist coverage stays on the old grid?</summary>

Document a hybrid architecture with explicit triggers and owners. Also review whether duplicated test data, secrets, and evidence retention create more operational cost than the split saves.

</details>

## Related documentation

* [Evaluation and governance](/evaluation-and-governance/evaluation.md)
* [Running tests across multiple browsers](/execution/cross-browser-testing.md)
* [Proxy and remote-browser profiles](/execution/proxy-and-remote-browser-profiles.md)
* [Parallel execution](/execution/parallel-execution.md)
* [Test results](/reporting/test-results.md)

{% hint style="info" %}
**Planning a browser-grid migration or consolidation?** [**Book an architecture review →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=browser_grid_migration) — Bring your required matrix and one diagnostic-heavy failure; we will map the observable migration boundary with you.
{% 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/evaluation-and-governance/browser-grid-migration-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.