> 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/test-case-management.md).

# Test Case Management

{% 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 %}

These 8 tools form the core CRUD layer for ContextQA test cases. Use them to build, inspect, and maintain your test library programmatically.

***

## `create_test_case`

Creates a new test case from a URL and a plain-English description of all steps to perform.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name               | Required | Type   | Description                                                               |
| ------------------ | -------- | ------ | ------------------------------------------------------------------------- |
| `url`              | ✅        | string | Starting URL for the test (e.g., `https://app.mycompany.com/login`)       |
| `task_description` | ✅        | string | Full natural language description of all steps and what to verify         |
| `pre_requisite`    | ❌        | string | Steps to perform before the main task (login, navigation setup, etc.)     |
| `name`             | ❌        | string | Display name for the test case; auto-generated from task if omitted       |
| `tags`             | ❌        | array  | Labels for filtering and grouping (e.g., `["smoke", "auth", "critical"]`) |

### Returns

JSON object with the created test case details, including the assigned `test_case_id`.

### Example

```json
{
  "url": "https://app.mycompany.com/login",
  "task_description": "Log in with username admin@test.com and password Admin123!. Verify the dashboard heading reads 'Welcome, Admin'. Click the Users menu item and verify the users table loads with at least one row.",
  "name": "Login — Admin user dashboard access",
  "tags": ["smoke", "auth", "admin"]
}
```

### Tips

* Include verification steps in `task_description` (e.g., "verify…", "confirm…", "check that…") — the AI creates assertion steps for them.
* Use `pre_requisite` for setup that should run before the timed test (clearing cookies, setting environment state).
* After creation, call `execute_test_case` to run it immediately.

### Related Tools

`get_test_case_steps` • `execute_test_case` • `update_test_case_step` • `delete_test_case`

***

## `get_test_cases`

Returns a paginated list of test cases in the current workspace with optional filtering and sorting.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name         | Required | Type    | Description                                                      |
| ------------ | -------- | ------- | ---------------------------------------------------------------- |
| `version_id` | ❌        | integer | Workspace version to scope the query; defaults to active version |
| `page`       | ❌        | integer | Page number (0-based, default: 0)                                |
| `size`       | ❌        | integer | Page size (default: 20, max: 100)                                |
| `sort_field` | ❌        | string  | Field to sort by (`name`, `created_at`, `updated_at`)            |
| `sort_order` | ❌        | string  | Sort direction: `asc` or `desc`                                  |
| `query`      | ❌        | string  | Keyword filter applied to test case names                        |

### Returns

JSON array of simplified test case objects, each containing `id`, `name`, `tags`, `created_at`, and `last_run_status`.

### Example

```json
{
  "size": 50,
  "sort_field": "updated_at",
  "sort_order": "desc",
  "query": "login"
}
```

### Related Tools

`query_contextqa` (semantic search) • `get_test_case_steps`

***

## `get_test_case_steps`

Returns the complete step definition of a test case, including all step actions, test data, and step IDs.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name           | Required | Type    | Description                 |
| -------------- | -------- | ------- | --------------------------- |
| `test_case_id` | ✅        | integer | Numeric ID of the test case |

### Returns

JSON object with `test_case_id`, `name`, and a `steps` array. Each step contains:

* `step_id` — unique step identifier (needed for `update_test_case_step` and `delete_test_case_step`)
* `position` — 0-based step index
* `action` — natural language step description
* `step_type` — `ai_text_actions`, `conditional`, `loop`, `api_call`, or `custom_code`
* `test_data` — any attached data values

### Example

```json
{
  "test_case_id": 18688
}
```

### Related Tools

`update_test_case_step` • `delete_test_case_step` • `create_complex_test_step`

***

## `update_test_case_step`

Updates an existing step at a specific position within a test case. Supports creating a new step at that position or overwriting an existing one.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name           | Required | Type    | Description                                                                       |
| -------------- | -------- | ------- | --------------------------------------------------------------------------------- |
| `test_case_id` | ✅        | integer | Test case containing the step                                                     |
| `position`     | ✅        | integer | 0-based step position to update                                                   |
| `step_data`    | ✅        | object  | Step object — must include `action` field with natural language description       |
| `event_type`   | ❌        | string  | `create_step` (insert) or `only_action` (update existing); default: `only_action` |

### Returns

String confirming the update with the step ID and position.

### Example

```json
{
  "test_case_id": 18688,
  "position": 2,
  "step_data": {
    "action": "Verify the welcome message reads 'Hello, Admin'"
  },
  "event_type": "only_action"
}
```

### Related Tools

`get_test_case_steps` • `delete_test_case_step` • `create_complex_test_step`

***

## `delete_test_case_step`

Permanently deletes a single step from a test case by its step ID.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name      | Required | Type    | Description                                          |
| --------- | -------- | ------- | ---------------------------------------------------- |
| `step_id` | ✅        | integer | Unique step ID (obtained from `get_test_case_steps`) |

### Returns

String confirming the deletion.

### Notes

* Step positions automatically resequence after deletion — if you delete position 2 from a 5-step test, the remaining steps renumber to 0, 1, 2, 3.
* Obtain `step_id` values by calling `get_test_case_steps` first.

### Related Tools

`get_test_case_steps` • `update_test_case_step`

***

## `delete_test_case`

Permanently deletes a test case and all its associated steps and execution history.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name           | Required | Type    | Description                           |
| -------------- | -------- | ------- | ------------------------------------- |
| `test_case_id` | ✅        | integer | Numeric ID of the test case to delete |

### Returns

String confirming success or failure.

### Warning

This operation is irreversible. All execution history, screenshots, and videos associated with this test case are also deleted.

### Related Tools

`get_test_cases` • `get_test_case_steps`

***

## `query_contextqa`

Searches across all test cases using AI-powered similarity matching. Use this to find existing test coverage before creating new test cases.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name    | Required | Type   | Description                                                                                   |
| ------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `query` | ✅        | string | Natural language description of what you want to find (e.g., "checkout flow with promo code") |

### Returns

Formatted string listing matching test cases ranked by semantic similarity, with their IDs and names.

### Example

```json
{
  "query": "user registration with email verification"
}
```

### Tips

* Always call `query_contextqa` before `create_test_case` to avoid creating duplicate tests.
* The query matches on meaning, not just keywords — "sign up" and "account creation" return similar results.

### Related Tools

`get_test_cases` • `create_test_case`

***

## `create_complex_test_step`

Adds an advanced step to a test case — supporting conditional logic, REST API calls, loops, and custom JavaScript code. Accepts a fully-formatted JSON payload string following the TestStep schema.

**Category:** Test Case Management **Authentication required:** Yes

### Parameters

| Name               | Required | Type   | Description                                                                   |
| ------------------ | -------- | ------ | ----------------------------------------------------------------------------- |
| `payload_json_str` | ✅        | string | JSON-encoded string of the complete step object following the TestStep schema |

### Returns

JSON object of the created step with its assigned `step_id`.

### Step Types

| `step_type`   | Use Case                                        |
| ------------- | ----------------------------------------------- |
| `conditional` | If/else logic branching on a condition          |
| `loop`        | Repeat steps N times or while a condition holds |
| `api_call`    | Make an HTTP request and store the response     |
| `custom_code` | Run arbitrary JavaScript in the browser context |

### Example — API call step

```json
{
  "payload_json_str": "{\"test_case_id\": 18688, \"position\": 1, \"step_type\": \"api_call\", \"action\": \"Call the authentication API and store the token\", \"api_config\": {\"method\": \"POST\", \"url\": \"${ENV.BASE_URL}/api/auth/login\", \"body\": {\"email\": \"admin@test.com\", \"password\": \"Admin123!\"}, \"store_response_as\": \"auth_token\", \"response_path\": \"$.token\"}}"
}
```

### Related Tools

`get_test_case_steps` • `update_test_case_step`


---

# 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/test-case-management.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.