> 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/managing-test-suites.md).

# Managing Test Suites

{% hint style="info" %}
**Who is this for?** Testers and SDETs who organize reusable test cases into feature, smoke, or regression collections before assigning them to a test plan.
{% endhint %}

A test suite is a reusable collection of test cases. Suites organize coverage; test plans assign suites to browsers or devices and provide the executable configuration.

## Before you begin

* Open **Plans → Test Suites** in the left navigation.
* Create test cases first if you want to populate the suite immediately. You can also create an empty suite and add cases later.
* Decide whether the suite targets **Web App**, **Mobile**, or **API** tests. The selected platform controls which compatible cases can be added.

## Find and review suites

The Test Suites page supports **List** and **Modular** views. Search by suite ID, title, or label, or use **Filter** to narrow the list. Each row shows the suite ID, name, platform, case count, latest result, dates, folder, and a **More actions** menu.

Click a suite to open its detail page. The header shows its ID, case count, platform, folder, and latest result. Use these tabs:

| Tab                    | Use                                                                              |
| ---------------------- | -------------------------------------------------------------------------------- |
| **Test Cases**         | Review and change the cases in the suite.                                        |
| **Used in Test Plans** | See which plans currently reference the suite.                                   |
| **History**            | Review changes to the suite.                                                     |
| **Settings**           | Update the suite name, prerequisites, folder, platform, labels, and description. |

## Create a test suite

1. On the Test Suites page, click **Create Test Suite**.
2. Complete **Suite Basics**:
   * **Suite Name** (required): use a short name that communicates the feature and purpose.
   * **Folder / Location**: leave the suite unorganized or place it in an existing folder.
   * **Prerequisites** (optional): select prerequisite test cases that must complete before the suite.
   * **Labels** (optional): add searchable classification such as `smoke`, `checkout`, or `release-gate`.
   * **Select Target Platform**: choose **Web App**, **Mobile**, or **API**.
   * **Description**: explain the coverage, owner, and intended trigger.
3. Choose one of the following:
   * **Add Test Cases** to continue to the case-selection step.
   * **Skip & create empty** to save the suite now and populate it later.
4. If adding cases, search or filter the compatible cases, select them, and finish creating the suite.

After ContextQA creates the suite, it opens the new suite's detail page so you can immediately review its cases, relationships, history, and settings.

### Example

| Field       | Example value                                                                 |
| ----------- | ----------------------------------------------------------------------------- |
| Suite name  | `Checkout smoke`                                                              |
| Folder      | `Commerce / Checkout`                                                         |
| Label       | `smoke`                                                                       |
| Platform    | `Web App`                                                                     |
| Description | `Critical checkout coverage for pull-request validation. Owner: QA Platform.` |

The example below shows the same fields on an existing suite's **Settings** tab.

![Test Suite Settings for a checkout smoke suite](/files/V96WJvOrgk343iGaurio)

## Add or remove test cases

1. Open the suite and stay on **Test Cases**.
2. Click **Manage Test Cases**.
3. Use **List** or **Modular** view, then search by test case ID or name. The **All**, **Added**, and **Not Added** tabs make the current membership explicit.
4. Select cases to add, or clear selected cases that should be removed.
5. Review the **to add** and **to remove** totals in the footer.
6. Click **Apply changes**.

Changing suite membership does not delete a test case from the workspace library. The case can remain in other suites.

{% hint style="warning" %}
Before removing a case, check **Used in Test Plans** and consider the effect on plan coverage and case totals.
{% endhint %}

## Update a suite

1. Open the suite.
2. Select **Settings**.
3. Change the name, prerequisite cases, folder, target platform, labels, or description.
4. Click **Save Changes**.

Use the **Used in Test Plans** tab after changing the platform or membership to confirm that every consuming plan still has the intended coverage.

## Create a test suite folder

The **New Folder** action is available only in **Modular** view.

1. Open **Plans → Test Suites**.
2. Select **Modular**.
3. To create a top-level folder, click **New Folder** in the page toolbar. To create a folder from the folder tree, use the **+** action in the **Folders** panel.
4. Enter the **Folder name** and click **Create folder**.

Use a folder for stable product or functional areas, such as `Commerce / Checkout`. Creating a folder does not move suites automatically; move existing suites into it after creation.

![Test Suites in Modular view with New Folder available in the toolbar and Folders panel](/files/HYje1XKyWemyJtIP8MM4)

## Move suites into a folder

Folders give the Test Suites page a hierarchy. You can place a suite in a folder when you create it, from its **Settings** tab, or by moving one or more suites together from the selection action bar.

1. On the Test Suites page, select the checkbox next to each suite you want to move. A selection action bar appears and shows the number of selected suites.
2. Click **Move to Folder**.
3. In the move dialog, select the destination folder. To leave the suites unorganized, select the root location.
4. Confirm the move. ContextQA moves the selected suites, reports how many moved, and refreshes the list.

To deselect every suite without moving anything, click **Clear selection** (the **X** icon) in the selection action bar.

{% hint style="info" %}
The selection action bar also provides **Delete** for the selected suites and **Edit** when exactly one suite is selected.
{% endhint %}

## Clone a suite

Cloning is useful when a new suite should start with the same membership as an existing one.

1. On the Test Suites page, open the suite's **More actions** menu.
2. Select **Clone suite**.
3. Give the clone a distinct name, review its configuration and membership, and save it.
4. Update any test plans that should use the clone.

## Delete a suite

1. Open the suite's **More actions** menu and select **Delete suite**, or open the suite's **Settings** tab and use the delete action.
2. Review the confirmation carefully. ContextQA warns that the suite and its associated run reports will be permanently removed.
3. Type `delete` to enable **Yes, Delete**.
4. Click **Yes, Delete** only after confirming that no active plan depends on the suite.

{% hint style="danger" %}
Deleting a suite cannot be undone. Test cases remain in the test case library, but the suite and its associated run reports do not.
{% endhint %}

## Practical organization patterns

| Pattern                   | Example               | Use                                           |
| ------------------------- | --------------------- | --------------------------------------------- |
| `[Feature] smoke`         | `Checkout smoke`      | Small, release-blocking coverage.             |
| `[Feature] regression`    | `Checkout regression` | Broad coverage for scheduled or release runs. |
| `[API resource] contract` | `Orders API contract` | API coverage grouped by resource.             |
| `[Platform] [feature]`    | `iOS onboarding`      | Mobile coverage with an explicit platform.    |

Use folders for hierarchy and labels for cross-cutting concerns. For example, put suites in `Commerce / Checkout`, then use `smoke` and `regression` labels to distinguish execution scope.

## Troubleshooting

**A case is missing from Manage Test Cases**

Confirm that the suite platform matches the test case type, clear filters, and search by the test case ID.

**Apply changes is disabled**

The button becomes active only after at least one membership change. Select a case to add or remove.

**The suite appears in a plan with zero cases**

Open the suite, select **Manage Test Cases**, and add cases. An empty suite can be assigned to a plan but contributes no executable cases.

**A suite is difficult to find**

Use a distinct name, move it to the appropriate folder, and add labels that match how the team searches for coverage.

## MCP automation

Use `get_test_suites` to discover suite IDs and `create_test_suite` to create a suite from test case IDs. Suite execution happens through a test plan. The current MCP suite/plan tools do not expose suite update or delete operations; use the portal for those actions.

See [Test Suites & Plans Tools](/mcp-server/tool-reference/suites-and-plans.md) for parameters and examples.

## Related pages

* [Creating Test Cases](/web-testing/creating-test-cases.md)
* [Test Plans](/web-testing/test-plans.md)
* [Running Tests](/execution/running-tests.md)
* [Scheduling Tests](/execution/scheduling.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 maintain tests 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/managing-test-suites.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.