> 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

{% hint style="info" %}
**Who is this for?** SDETs, developers, and DevOps engineers integrating ContextQA with AI coding assistants (Claude, Cursor) or CI/CD pipelines.
{% endhint %}

Test suites group related test cases for batch execution. Test plans bundle multiple suites together for full-regression or scheduled runs. Use these tools to list, execute, and monitor suite- and plan-level executions.

***

## get\_test\_suites

Retrieves a paginated list of test suites in the workspace; use this to discover suite IDs before executing.

**Category:** Test Suites & Plans | **Authentication required:** Yes

### Parameters

| Name  | Required | Type    | Description                                  |
| ----- | -------- | ------- | -------------------------------------------- |
| page  | ❌        | integer | Page number (0-based). Defaults to 0.        |
| size  | ❌        | integer | Results per page. Defaults to 20.            |
| sort  | ❌        | string  | Sort field and direction, e.g. `"name,asc"`. |
| query | ❌        | string  | Free-text filter applied to suite names.     |

### Returns

Paginated JSON object with `content` array of suite records. Each record includes `id`, `name`, `description`, and `testCaseCount`.

### Example

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

### Related Tools

`execute_test_suite`, `get_test_plans`, `get_test_cases`

***

## execute\_test\_suite

Triggers execution of all test cases within a suite and returns an execution confirmation with the resulting execution ID.

**Category:** Test Suites & Plans | **Authentication required:** Yes

### Parameters

| Name            | Required | Type    | Description                              |
| --------------- | -------- | ------- | ---------------------------------------- |
| test\_suite\_id | ✅        | integer | Numeric ID of the test suite to execute. |

### Returns

JSON confirmation with `execution_id` and execution start metadata. Use `get_execution_status` with the returned ID to poll progress.

### Example

```json
{
  "test_suite_id": 42
}
```

### Related Tools

`get_test_suites`, `get_execution_status`, `get_test_case_results`

***

## get\_test\_plans

Retrieves a paginated list of test plans; use this to discover plan IDs before triggering a plan-level execution.

**Category:** Test Suites & Plans | **Authentication required:** Yes

### Parameters

| Name  | Required | Type    | Description                                        |
| ----- | -------- | ------- | -------------------------------------------------- |
| page  | ❌        | integer | Page number (0-based). Defaults to 0.              |
| size  | ❌        | integer | Results per page. Defaults to 20.                  |
| sort  | ❌        | string  | Sort field and direction, e.g. `"createdAt,desc"`. |
| query | ❌        | string  | Free-text filter applied to plan names.            |

### Returns

Paginated JSON object with `content` array of test plan records. Each record includes `id`, `name`, `suiteCount`, and `lastRunStatus`.

### Example

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

### Related Tools

`execute_test_plan`, `get_test_plan_execution_status`, `get_test_suites`

***

## execute\_test\_plan

Executes a full test plan, optionally using a custom AI agent persona or knowledge base to guide execution behaviour.

**Category:** Test Suites & Plans | **Authentication required:** Yes

### Parameters

| Name           | Required | Type    | Description                                                            |
| -------------- | -------- | ------- | ---------------------------------------------------------------------- |
| test\_plan\_id | ✅        | integer | Numeric ID of the test plan to execute.                                |
| persona\_id    | ❌        | string  | ID of a custom agent persona to use. Obtain from `list_custom_agents`. |
| knowledge\_id  | ❌        | string  | ID of a knowledge base to attach. Obtain from `list_knowledge_bases`.  |

### Returns

JSON with an `execution_id` string and a human-readable `message` confirming the plan was queued.

### Example

```json
{
  "test_plan_id": 7,
  "persona_id": "persona_8f3a1c",
  "knowledge_id": "kb_2b9d4e"
}
```

### Related Tools

`get_test_plans`, `get_test_plan_execution_status`, `rerun_test_plan`, `list_custom_agents`, `list_knowledge_bases`

***

## get\_test\_plan\_execution\_status

Polls the status of a running or completed test plan execution; call repeatedly until `SUCCESS` or `FAILURE` is returned.

**Category:** Test Suites & Plans | **Authentication required:** Yes

### Parameters

| Name          | Required | Type   | Description                                   |
| ------------- | -------- | ------ | --------------------------------------------- |
| execution\_id | ✅        | string | Execution ID returned by `execute_test_plan`. |

### Returns

JSON object with `status` (`IN_PROGRESS`, `SUCCESS`, `FAILURE`), overall pass/fail counts, and per-suite breakdown. Poll every 10–30 seconds until a terminal status is reached.

### Example

```json
{
  "execution_id": "plan_exec_9a72bc"
}
```

### Related Tools

`execute_test_plan`, `rerun_test_plan`, `get_execution_status`

***

## rerun\_test\_plan

Re-executes a previously run test plan using the same configuration, useful for re-checking a plan after a fix without reconfiguring execution parameters.

**Category:** Test Suites & Plans | **Authentication required:** Yes

### Parameters

| Name          | Required | Type   | Description                                     |
| ------------- | -------- | ------ | ----------------------------------------------- |
| execution\_id | ✅        | string | Execution ID of the original plan run to rerun. |

### Returns

JSON with a new `execution_id` for the rerun and a confirmation message. Use `get_test_plan_execution_status` to track progress.

### Example

```json
{
  "execution_id": "plan_exec_9a72bc"
}
```

### Related Tools

`execute_test_plan`, `get_test_plan_execution_status`, `get_test_plans`

***


---

# 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.