> 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/web-testing/test-plans.md).

# Test Plans

{% hint style="info" %}
**Who is this for?** Testers, SDETs, and QA managers who turn reusable suites into browser or device-specific execution plans.
{% endhint %}

A test plan is the executable configuration in ContextQA. It maps one or more test suites to browsers or devices and defines parallelism, timeouts, screenshots, environments, knowledge, notifications, and recovery behavior.

## Before you begin

* Create at least one [test suite](/web-testing/managing-test-suites.md). A suite can be empty while you configure a plan, but it will contribute zero executable cases.
* Open **Plans → Test Plans**.
* Decide which browser or device should run each suite and whether the plan needs an environment or knowledge base.

## Find and review plans

The page has **Test Plans** and **Schedules** tabs. Search by ID, title, or label, use **Filter** to narrow the list, or combine a search term with filters to find a precise subset. ContextQA applies both conditions to the same result set. Clear the search term and active filter chips to return to the full list.

A plan row shows its name, suite and case totals, latest run result, and actions for **Schedule**, **Reports**, **Clone**, and **Run**.

Click a plan name to open its detail page. The header provides **Run Manually**, **Run Now**, and a menu for **Copy**, **Edit**, and **Delete**. The summary shows suite and case totals and the current schedule state.

The detail page includes:

| Tab                   | Use                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------- |
| **Overview**          | Review plan metadata and the suite-to-browser/device mapping. Add suites or view their cases. |
| **Runs**              | Review recent plan runs.                                                                      |
| **Reports**           | Open run reports.                                                                             |
| **Schedules**         | Create and manage recurring execution.                                                        |
| **CI / CD**           | Review pipeline integrations and programmatic triggers.                                       |
| **Settings**          | Update execution, notification, and recovery settings.                                        |
| **Execution History** | Compare execution outcomes over time.                                                         |
| **Version History**   | Audit plan configuration changes.                                                             |

![Test Plan overview with one suite assigned to Chromium](/files/Mvo5V892zER3xrE0viDY)

## Create a test plan

Click **New Test Plan** to open the three-step wizard.

### Step 1: Create Test Plan

Enter the plan's identity and presentation settings:

* **Test Plan Name** (required)
* **Labels** and **Description** (optional)
* **Hide on Dashboard**
* **Send Notification** for email and connected Slack notifications when the plan runs
* **Viewport**: Desktop, Laptop, Tablet, or Mobile
* **Resolution**

Example:

| Field       | Example value                                                                       |
| ----------- | ----------------------------------------------------------------------------------- |
| Name        | `Checkout PR gate`                                                                  |
| Description | `Runs the checkout smoke suite before each production release. Owner: QA Platform.` |
| Viewport    | `Desktop`                                                                           |
| Resolution  | `Full HD (1920×1080)`                                                               |

Click **Next**.

### Step 2: Test Machines & Suites Selection

1. Click **Add Test Suites**.
2. Search by suite name and optionally filter by label.
3. Select suites in **Available Test Suites**, move them to **Selected Test Suites**, and click **Add**.

![Selecting the checkout smoke suite for a Test Plan](/files/w2MJaKCUzFLOLQhSvbkj)

4. Select one or more suite rows and click **Add Machine/Device**.
5. Enter a configuration name, such as `Chrome desktop`.
6. Choose the test lab type, platform, and browser or device. Browser choices can include Firefox, Safari, Microsoft Edge, Chromium, and Chrome (Beta), depending on workspace availability.
7. Click **Create** to attach the machine or device to the selected suites.
8. Repeat the mapping when different suites need different targets, then click **Next**.

![A checkout smoke suite mapped to a Chromium machine](/files/rQW1fCCrflsZcFXYpO0H)

{% hint style="info" %}
A plan can contain multiple machine or device configurations. The same suite can be mapped to more than one target for cross-browser or cross-device coverage.
{% endhint %}

### Step 3: Test Plan Settings

Set **Parallel Execution** to the number of execution nodes the plan may use. Start with `1` while validating a new plan.

Expand **Additional Settings** to configure:

| Setting                 | Purpose                                              |
| ----------------------- | ---------------------------------------------------- |
| **Page Load Timeout**   | Seconds to wait for navigation to complete.          |
| **Element Timeout**     | Seconds to wait for a target element.                |
| **Environments**        | Supplies environment-specific URLs and variables.    |
| **Capture Screenshots** | Controls when step screenshots are captured.         |
| **Knowledge Base**      | Supplies application context to the execution agent. |

Expand **Recovery Actions** to configure:

| Failure condition               | Available responses                                                          |
| ------------------------------- | ---------------------------------------------------------------------------- |
| Major test step failure         | Abort and run the next test case; report and continue to the next test step. |
| Test step prerequisite failure  | Abort and run the next test case; report and continue to the next test step. |
| Test case prerequisite failure  | Abort the test plan; report and continue to the next test case.              |
| Test case abort                 | Clean up and reuse the current session; start with a new session.            |
| Test suite prerequisite failure | Abort the test plan; report and continue to the next suite.                  |
| Rerun on failure                | None; all test cases; all failed test cases.                                 |

![Test Plan execution settings with additional settings and recovery actions](/files/m98BhseYCxX15RnEtHCM)

Click **Create**. ContextQA opens the plan's **Overview** page after saving it.

## Update a test plan

Use either update path, depending on what you need to change.

### Edit details, mappings, or creation settings

1. Open the plan.
2. Open the header menu and select **Edit**.
3. Move through the same three-step wizard. Change the name, description, labels, dashboard visibility, notifications, viewport, suite-to-device mappings, or plan settings.
4. Click **Update** on the final step.

### Edit runtime settings directly

1. Open the plan and select **Settings**.
2. Change **Parallel Nodes**, screenshot capture, page or element timeouts, knowledge base, environment, notification toggles, or recovery actions.
3. Click **Save Changes**. Use **Discard** to abandon unsaved changes.

ContextQA records plan changes in **Version History**. Use this tab to audit changes and, when available, compare or restore a prior plan version.

## Change suite membership

* To add coverage from **Overview**, click **Add Test Suite**, choose suites, and assign the required browser or device configuration.
* To inspect membership without editing it, click **View Test Cases** on a suite row.
* To remove or remap suites, open **Edit** and use step 2 of the wizard.

After any membership change, confirm the suite and test case totals shown in the header.

## Clone or copy a plan

Use **Clone** from the Test Plans list or **Copy** from the plan header menu when a new plan should start from an existing configuration. Give the copy a distinct name, then review its suites, devices, environment, notifications, and schedule before running it.

## Run and monitor a plan

* Use **Run Manually** when you need to review or adjust the manual run configuration.
* Use **Run Now** for an immediate execution using the saved configuration.
* Review progress and results in **Runs**, **Reports**, and **Execution History**.

Running tests changes execution state and can consume capacity. Verify the target environment, data, and device mapping before starting a run.

## Schedule a plan

Open **Schedules** on the plan detail page or use **Schedule** from the list. Create a schedule with a name, start date and time, recurrence, and notification recipient. Existing schedules can be activated, paused, edited, run immediately, or deleted.

For a dedicated walkthrough, see [Scheduling Tests](/execution/scheduling.md).

## Delete a test plan

1. Open the plan.
2. Open the header menu and select **Delete**.
3. Review the confirmation. ContextQA warns that the plan and all associated run reports will be permanently removed.
4. Type `delete` to enable **Yes, Delete**.
5. Click **Yes, Delete** only when the plan and its historical reports are no longer required.

![Test Plan deletion requires typing delete before confirmation](/files/Nu2JbOMVxRrebaP08IOm)

{% hint style="danger" %}
Deleting a test plan cannot be undone. Deleting the plan does not delete its underlying suites or test cases, but it removes the plan and its associated run reports.
{% endhint %}

## MCP automation

The ContextQA MCP server supports this workflow:

1. Discover or create suites with `get_test_suites` and `create_test_suite`.
2. Discover browsers or mobile devices with `get_available_devices`.
3. Create the plan with `create_test_plan` and map each device configuration to one or more suite IDs.
4. Run it with `execute_test_plan`.
5. Poll with `get_test_plan_execution_status`; use `rerun_test_plan` when a previous execution should run again.

The current MCP suite/plan tools do not expose update or delete operations. Use the portal for those actions. See [Test Suites & Plans Tools](/mcp-server/tool-reference/suites-and-plans.md) for exact parameters and examples.

## Troubleshooting

**Add Machine/Device is disabled**

Select at least one suite row first.

**Next is blocked on the suite and machine step**

Confirm that at least one selected suite has a browser or device configuration.

**A suite contributes zero test cases**

Open the suite and use **Manage Test Cases** to add compatible cases.

**The plan is missing from the dashboard**

Open **Settings** and turn off **Hide on Dashboard**.

**Search and filters return no plans**

Clear the search term and remove active filter chips one at a time. Search and filters are cumulative, so a plan must satisfy both when they are used together.

**A run does not start**

Confirm that another run is not already active, the mapped browser or device is available, and the plan has executable test cases.

## Related pages

* [Managing Test Suites](/web-testing/managing-test-suites.md)
* [Running Tests](/execution/running-tests.md)
* [Scheduling](/execution/scheduling.md)
* [Parallel Execution](/execution/parallel-execution.md)
* [Environments](/execution/environments.md)
* [Mobile Test Plans](/mobile-testing/mobile-test-plans.md)
* [Integrations Overview](/integrations/integrations.md)

{% hint style="info" %}
**70% less manual test maintenance with AI self-healing.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See ContextQA create and run test plans for your web application.
{% 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/web-testing/test-plans.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.