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