> 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/execution/cross-browser-testing.md).

# Running Tests Across Multiple Browsers

{% hint style="info" %}
**Who is this for?** SDETs, QA managers, and developers who need to confirm that a web application behaves the same way on Chrome, Firefox, and Safari — without maintaining a separate test plan for each browser.
{% endhint %}

A feature that works in Chrome can still break in Safari or Firefox. Layout shifts, unsupported APIs, and rendering differences only surface when you run the same flow on each browser engine. ContextQA runs your tests on real browsers — Chromium (Chrome), Firefox, and WebKit (Safari) — so you can verify cross-browser compatibility from one place.

This guide shows you how to build a single **Cross Browser Testing** plan that runs the same test suite on multiple browsers, run it, and read the per-browser results.

## Goal

Run one test suite on Chrome, Firefox, and Safari from a single test plan, and confirm each browser passed.

## Prerequisites

* A ContextQA account with at least one workspace ([sign up](https://accounts.contextqa.com/onboard)).
* A test suite that contains one or more passing web test cases. If you don't have one, see [Managing Test Suites](/web-testing/managing-test-suites.md).
* An environment configured with the base URL of the application you want to test. See [Configuring Environments](/execution/environments.md).
* Familiarity with [test plans](/web-testing/test-plans.md) — the configuration that defines what runs, where, and how.

***

## Step 1: Create a cross-browser test plan

A test plan defines which suites run, which browsers they target, and how the run behaves on failure. ContextQA creates a test plan through a three-step wizard.

1. Open the **Test Plans** tab in Test Development.
2. Click **Create Test Plan**.
3. Configure the plan basics:
   * **Test Plan Name** — name it for its purpose, such as `Cross-Browser — Checkout — Staging`.
   * **Environment** — select the environment whose base URL the tests run against.
   * **Test plan type** — select **Cross Browser Testing**. This is the plan type that runs tests on multiple browsers. (Choose **Cross Device Testing** only for mobile suites.)
4. Click **Next**.

**Verify it worked:** The wizard advances to the **Test Machines & Suites Selection** step.

***

## Step 2: Add the first browser

Each browser you target is configured as a **test machine** — a combination of platform, browser, and resolution. Start by adding Chrome.

1. On the **Test Machines & Suites Selection** step, under **Select Platform**, choose the operating system to run on.
2. Under **Browser**, select **Chrome**.
3. Set the **Resolution** for the run.
4. Under **Selected Test Suites**, add the suite you want to run across browsers.

**Verify it worked:** The suite appears under **Selected Test Suites**, assigned to a Chrome machine.

***

## Step 3: Add Firefox and Safari

To test the same suite on additional browsers, add a machine for each one.

1. Click **Add Machine/Device**, then choose **Create new Machine**.
2. In the machine form, select the **Platform**, set **Browser** to **Firefox**, and choose a **Resolution**.
3. Add the same test suite to the new Firefox machine.
4. Repeat for Safari: click **Add Machine/Device**, choose **Create new Machine**, set **Browser** to **Safari**, and add the same suite.

You now have one plan with three machines — Chrome, Firefox, and Safari — each running the same suite.

{% hint style="info" %}
To reuse a browser machine you already configured for a different suite, choose **Add to existing Machine** instead of **Create new Machine**.
{% endhint %}

5. Set the suite execution behavior:
   * **Run Test Suites in Parallel** — enable this to run the browsers at the same time for faster feedback. See [Parallel Execution](/execution/parallel-execution.md) for how concurrency is allocated.
   * **Reset Session for Every Test Case** — enable this so each test case starts from a clean browser session.
6. Click **Next**.

**Verify it worked:** All three machines (Chrome, Firefox, Safari) are listed, each with the suite assigned.

***

## Step 4: Configure failure handling and save

On the final **Test Plan Settings** step, decide how the run handles failures.

1. Under **Recovery Actions**, enable **Rerun on failure** if you want ContextQA to retry a failed test case once before reporting it as failed. This filters out transient flakiness so a one-off network blip doesn't read as a real browser incompatibility.
2. Review the remaining recovery options, then adjust them to match your team's tolerance for partial runs.
3. Click **Save** (or **Create Test Plan**) to finish.

**Verify it worked:** The new plan appears in the **Test Plans** list with the name you gave it.

***

## Step 5: Run the plan

1. Open the plan from the **Test Plans** list.
2. Click **Run Manually** in the plan header.

ContextQA runs the suite on all three browsers. With **Run Test Suites in Parallel** enabled, the browser runs execute concurrently.

***

## Verification

Confirm every browser ran and passed.

1. Open the run from the test plan execution results. The plan dashboard shows the overall pass/fail status for the run.
2. Expand the suite detail. Each test case row lists the **browser/device used**, so you can see the same case reported once per browser.
3. Confirm each browser shows a **PASSED** status.

If one browser fails while the others pass, you have found a browser-specific defect. Open that execution's [test results](/reporting/test-results.md) — the per-step screenshots, session video, and console log show exactly where the behavior diverged on that browser.

***

## Troubleshooting

**A browser I want isn't listed in the Browser dropdown** The available browsers depend on your workspace configuration and subscription tier. ContextQA supports Chromium (Chrome), Firefox, and WebKit (Safari). If a browser is missing, confirm your plan includes it or contact your workspace administrator.

**A suite ran on one browser but not the others** Open the plan's **Test Machines & Suites Selection** step and confirm the suite is listed under **Selected Test Suites** for every machine. A suite added to the Chrome machine only runs on Chrome unless you also add it to the Firefox and Safari machines.

**All browsers fail at the same step** A failure that reproduces on every browser is usually a genuine application issue or a test problem, not a compatibility defect. Review the failing step in the [test results](/reporting/test-results.md), and check [Failure Analysis](/reporting/failure-analysis.md) for AI root cause analysis.

**One browser is consistently slower or times out** Different browser engines render at different speeds. If a single browser intermittently fails on timing, enable **Rerun on failure** in the plan settings, and review [Flaky Test Detection](/reporting/flaky-test-detection.md) to confirm the failures are transient rather than a real defect.

***

## Related pages

* [Test Plans](/web-testing/test-plans.md) — the full test plan configuration reference
* [Parallel Execution](/execution/parallel-execution.md) — run browsers concurrently to cut total run time
* [Configuring Environments](/execution/environments.md) — point one plan at staging, QA, or production
* [Test Results](/reporting/test-results.md) — read per-browser execution reports
* [Tutorial: Build and Schedule a Regression Suite](/execution/regression-suite-tutorial.md) — schedule a cross-browser plan to run automatically

{% hint style="info" %}
**Run one test suite across every browser, in parallel.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See ContextQA run your tests on Chrome, Firefox, and Safari at once.
{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://learning.contextqa.com/execution/cross-browser-testing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.