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

***