Test Suites & Plans
MCP reference for discovering and creating test suites and plans, selecting devices, executing plans, and monitoring or rerunning executions.
Quick answer
MCP reference for discovering and creating test suites and plans, selecting devices, executing plans, and monitoring or rerunning executions. Use this reference to choose the appropriate tools, understand their required inputs, and interpret their user-visible outputs.
What this page covers
Test suites organize test cases. Test plans map suites to browsers or devices and provide the executable configuration. Use the suite and plan tools in this order:
Find test cases and create a suite.
Discover available browsers or devices.
Create a plan that maps those targets to suite IDs.
Execute the plan and poll its status.
get_test_suites
Lists test suites in the current or specified workspace.
page
No
integer
Zero-based page number.
size
No
integer
Page size.
sort
No
string
API sort expression.
query
No
string
API filter or search query.
workspace_version_id
No
integer
Workspace version to query. Defaults to the connection's current workspace.
Use a returned suite ID when creating a test plan.
create_test_suite
Creates a named suite from existing test case IDs.
name
Yes
string
Suite name.
test_case_ids
Yes
integer[]
Test case IDs to include. Use get_test_cases to discover them.
test_type
No
string
BROWSER (default), MOBILE, or API_TESTCASE.
description
No
string
Suite purpose and scope.
tags
No
string[] or string
Labels as a list or comma-separated string.
parent_id
No
integer
Parent suite ID. Use 0 for a top-level suite.
workspace_version_id
No
integer
Target workspace version. Defaults to the connection's current workspace.
Record the returned suite ID for create_test_plan.
get_available_devices
Lists the target catalog used when creating a test plan.
device_type
No
string
Use browser (default) for browser targets or device for mobile devices.
For a browser plan, pass a returned device_key, such as chromium, firefox, webkit, edge, or chrome, as the device object's browser value. For mobile, use the returned device name.
get_test_plans
Lists test plans in the current or specified workspace.
page
No
integer
Zero-based page number.
size
No
integer
Page size.
sort
No
string
API sort expression.
query
No
string
API filter or search query.
workspace_version_id
No
integer
Workspace version to query. Defaults to the connection's current workspace.
create_test_plan
Creates an execution plan and maps one or more suite IDs to browser or device configurations.
name
Yes
string
Plan name.
devices
Yes
object[]
Browser/device configurations and their suite IDs.
description
No
string
Plan purpose and scope.
parallel_nodes
No
integer
Number of configurations that may execute concurrently. Defaults to 1.
page_timeout
No
integer
Maximum seconds to wait for page load. Defaults to 30.
element_timeout
No
integer
Maximum seconds to wait for an element. Defaults to 30.
knowledge_id
No
string
Knowledge base ID. Use none when no specific knowledge base is needed.
persona_id
No
string
AI persona ID. Use default unless a custom persona is configured.
workspace_version_id
No
integer
Target workspace version. Defaults to the connection's current workspace.
Each object in devices supports:
browser
Yes
Browser key or mobile device name.
suite_ids
Yes
Suite IDs to run on this target.
title
No
Human-readable configuration name. Defaults to the browser/device name.
platform
No
Browser (default) or Devices for mobile.
Single-browser example:
Cross-browser and mobile example:
Record the returned plan ID for execution.
execute_test_plan
Starts a saved test plan.
test_plan_id
Yes
integer
Plan ID returned by create_test_plan or get_test_plans.
knowledge_id
No
string
Optional knowledge base override for this run.
Running a plan creates execution state and can consume test capacity. Record the returned execution ID and poll it with get_test_plan_execution_status.
get_test_plan_execution_status
Returns the current state of a plan execution.
execution_id
Yes
integer
Execution ID returned by execute_test_plan or rerun_test_plan.
Poll at a reasonable interval until the execution reaches a terminal state. Avoid starting duplicate executions while a run is active.
Response contract and mixed outcomes
The status response describes the plan execution as a whole. Depending on the execution phase, it can include:
id, testPlanId, testPlanName
Execution and plan identity.
status, result, message
Current lifecycle state, overall result, and any execution message.
totalCount
Number of test-case results currently associated with the execution.
passedCount, failedCount
Passed and failed test-case counts.
abortedCount, stoppedCount, notExecutedCount, queuedCount
Non-passing or not-yet-run outcome counts.
startTime, endTime, duration, totalDuration
Available timing data.
Counts can be partial while a plan is running. A terminal plan can also contain mixed outcomes—for example, three passed cases and one failed case—so do not infer that every case has the same result as the plan's overall result field.
get_test_plan_execution_status reports aggregate progress; it does not return a live, per-case step timeline. After the plan reaches a terminal state, call get_test_case_results with the plan execution_id to retrieve its case-level result records. Use each returned result ID with the step-result or evidence tools when deeper diagnosis is needed.
rerun_test_plan
Re-executes a previous plan execution using its saved configuration.
execution_id
Yes
integer
Prior plan execution ID.
The response provides a new execution to monitor with get_test_plan_execution_status.
Related pages
Last updated
Was this helpful?