> 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/mcp-server/tool-reference/suites-and-plans.md).

# Test Suites & Plans

## Quick answer

MCP reference for discovering and creating test suites and plans, selecting devices, executing plans, and monitoring or rerunning executions. Use this reference to choose the appropriate tools, understand their required inputs, and interpret their user-visible outputs.

## What this page covers

{% hint style="info" %}
**Who is this for?** SDETs, developers, and DevOps engineers using ContextQA from an MCP-compatible assistant or automated workflow.
{% endhint %}

Test suites organize test cases. Test plans map suites to browsers or devices and provide the executable configuration. Use the suite and plan tools in this order:

1. Find test cases and create a suite.
2. Discover available browsers or devices.
3. Create a plan that maps those targets to suite IDs.
4. Execute the plan and poll its status.

{% hint style="warning" %}
Suites are not executed directly by the current MCP tools. Run them through a test plan. Suite and plan update or delete tools are not currently exposed; use the ContextQA portal for those actions.
{% endhint %}

## get\_test\_suites

Lists test suites in the current or specified workspace.

| Parameter              | Required | Type    | Description                                                                 |
| ---------------------- | -------: | ------- | --------------------------------------------------------------------------- |
| `page`                 |       No | integer | Zero-based page number.                                                     |
| `size`                 |       No | integer | Page size.                                                                  |
| `sort`                 |       No | string  | API sort expression.                                                        |
| `query`                |       No | string  | API filter or search query.                                                 |
| `workspace_version_id` |       No | integer | Workspace version to query. Defaults to the connection's current workspace. |

```json
{
  "page": 0,
  "size": 20,
  "query": "checkout"
}
```

Use a returned suite ID when creating a test plan.

## create\_test\_suite

Creates a named suite from existing test case IDs.

| Parameter              | Required | Type                | Description                                                               |
| ---------------------- | -------: | ------------------- | ------------------------------------------------------------------------- |
| `name`                 |      Yes | string              | Suite name.                                                               |
| `test_case_ids`        |      Yes | integer\[]          | Test case IDs to include. Use `get_test_cases` to discover them.          |
| `test_type`            |       No | string              | `BROWSER` (default), `MOBILE`, or `API_TESTCASE`.                         |
| `description`          |       No | string              | Suite purpose and scope.                                                  |
| `tags`                 |       No | string\[] or string | Labels as a list or comma-separated string.                               |
| `parent_id`            |       No | integer             | Parent suite ID. Use `0` for a top-level suite.                           |
| `workspace_version_id` |       No | integer             | Target workspace version. Defaults to the connection's current workspace. |

```json
{
  "name": "Checkout smoke",
  "description": "Critical checkout coverage for pull-request validation.",
  "tags": ["smoke", "checkout"],
  "test_type": "BROWSER",
  "test_case_ids": [1201, 1202, 1203]
}
```

Record the returned suite ID for `create_test_plan`.

## get\_available\_devices

Lists the target catalog used when creating a test plan.

| Parameter     | Required | Type   | Description                                                                 |
| ------------- | -------: | ------ | --------------------------------------------------------------------------- |
| `device_type` |       No | string | Use `browser` (default) for browser targets or `device` for mobile devices. |

```json
{
  "device_type": "browser"
}
```

For a browser plan, pass a returned `device_key`, such as `chromium`, `firefox`, `webkit`, `edge`, or `chrome`, as the device object's `browser` value. For mobile, use the returned device name.

## get\_test\_plans

Lists test plans in the current or specified workspace.

| Parameter              | Required | Type    | Description                                                                 |
| ---------------------- | -------: | ------- | --------------------------------------------------------------------------- |
| `page`                 |       No | integer | Zero-based page number.                                                     |
| `size`                 |       No | integer | Page size.                                                                  |
| `sort`                 |       No | string  | API sort expression.                                                        |
| `query`                |       No | string  | API filter or search query.                                                 |
| `workspace_version_id` |       No | integer | Workspace version to query. Defaults to the connection's current workspace. |

```json
{
  "page": 0,
  "size": 20,
  "query": "release gate"
}
```

## create\_test\_plan

Creates an execution plan and maps one or more suite IDs to browser or device configurations.

| Parameter              | Required | Type      | Description                                                               |
| ---------------------- | -------: | --------- | ------------------------------------------------------------------------- |
| `name`                 |      Yes | string    | Plan name.                                                                |
| `devices`              |      Yes | object\[] | Browser/device configurations and their suite IDs.                        |
| `description`          |       No | string    | Plan purpose and scope.                                                   |
| `parallel_nodes`       |       No | integer   | Number of configurations that may execute concurrently. Defaults to `1`.  |
| `page_timeout`         |       No | integer   | Maximum seconds to wait for page load. Defaults to `30`.                  |
| `element_timeout`      |       No | integer   | Maximum seconds to wait for an element. Defaults to `30`.                 |
| `knowledge_id`         |       No | string    | Knowledge base ID. Use `none` when no specific knowledge base is needed.  |
| `persona_id`           |       No | string    | AI persona ID. Use `default` unless a custom persona is configured.       |
| `workspace_version_id` |       No | integer   | Target workspace version. Defaults to the connection's current workspace. |

Each object in `devices` supports:

| Key         | Required | Description                                                             |
| ----------- | -------: | ----------------------------------------------------------------------- |
| `browser`   |      Yes | Browser key or mobile device name.                                      |
| `suite_ids` |      Yes | Suite IDs to run on this target.                                        |
| `title`     |       No | Human-readable configuration name. Defaults to the browser/device name. |
| `platform`  |       No | `Browser` (default) or `Devices` for mobile.                            |

Single-browser example:

```json
{
  "name": "Checkout PR gate",
  "description": "Runs checkout smoke coverage before production releases.",
  "parallel_nodes": 1,
  "page_timeout": 30,
  "element_timeout": 30,
  "devices": [
    {
      "browser": "chromium",
      "suite_ids": [172],
      "title": "Chromium desktop"
    }
  ]
}
```

Cross-browser and mobile example:

```json
{
  "name": "Cross-platform release gate",
  "parallel_nodes": 2,
  "devices": [
    {
      "browser": "chromium",
      "suite_ids": [172, 173],
      "title": "Chromium regression"
    },
    {
      "browser": "iPhone 15",
      "suite_ids": [174],
      "title": "iPhone smoke",
      "platform": "Devices"
    }
  ]
}
```

Record the returned plan ID for execution.

## execute\_test\_plan

Starts a saved test plan.

| Parameter      | Required | Type    | Description                                                 |
| -------------- | -------: | ------- | ----------------------------------------------------------- |
| `test_plan_id` |      Yes | integer | Plan ID returned by `create_test_plan` or `get_test_plans`. |
| `knowledge_id` |       No | string  | Optional knowledge base override for this run.              |

```json
{
  "test_plan_id": 133
}
```

Running a plan creates execution state and can consume test capacity. Record the returned execution ID and poll it with `get_test_plan_execution_status`.

## get\_test\_plan\_execution\_status

Returns the current state of a plan execution.

| Parameter      | Required | Type    | Description                                                        |
| -------------- | -------: | ------- | ------------------------------------------------------------------ |
| `execution_id` |      Yes | integer | Execution ID returned by `execute_test_plan` or `rerun_test_plan`. |

```json
{
  "execution_id": 9812
}
```

Poll at a reasonable interval until the execution reaches a terminal state. Avoid starting duplicate executions while a run is active.

## rerun\_test\_plan

Re-executes a previous plan execution using its saved configuration.

| Parameter      | Required | Type    | Description              |
| -------------- | -------: | ------- | ------------------------ |
| `execution_id` |      Yes | integer | Prior plan execution ID. |

```json
{
  "execution_id": 9812
}
```

The response provides a new execution to monitor with `get_test_plan_execution_status`.

## Related pages

* [Managing Test Suites](/web-testing/managing-test-suites.md)
* [Test Plans](/web-testing/test-plans.md)
* [MCP Server overview](/mcp-server/overview.md)
* [MCP tool reference](/mcp-server/tool-reference.md)


---

# 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/mcp-server/tool-reference/suites-and-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.