Test Case Management

Complete reference for the 8 MCP tools that create, read, update, delete, and query test cases in ContextQA.

Who is this for? SDETs, developers, and DevOps engineers integrating ContextQA with AI coding assistants (Claude, Cursor) or CI/CD pipelines.

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

{
  "url": "https://app.mycompany.com/login",
  "task_description": "Log in with username [email protected] 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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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\": \"[email protected]\", \"password\": \"Admin123!\"}, \"store_response_as\": \"auth_token\", \"response_path\": \"$.token\"}}"
}

Related Tools

get_test_case_steps • update_test_case_step