product: assert audience: test-developer, operator, ai-assistant authority: normative

MCP Tools — Test Execution

Tools for starting, monitoring, and aborting test runs.

All tool responses include a top-level station field containing the StationLabel configured for this server instance.

See also: tools-reference.md for the full tool index.

start_test

Start a test execution from a YAML file path.

⚠️ A station runs up to its number of execution slots at once — MaxParallelExecutions (default 1), capped by the runner pool. get_station_info reports slots.slotCount and which slots are busy. Calling start_test when every slot is busy returns 409 Conflict ("Station at capacity").

Each start_test that finds a free slot starts immediately and returns its own executionId; each run is independent. Steps that share an instrument must declare requires: (see yaml/runtime-control.md).

If asked to run a test multiple times (e.g. "run 10 times and report the average"), run them one after another when the user asks for sequential runs or the station has a single slot:

1. Call start_test
2. Wait for it to finish — use wait_for_test_completion or poll get_test_status until verdict is no longer RUNNING
3. Repeat from step 1

Returns: execution — executionId, testName, status, startTime

Calls: POST /api/testexecution/run

Error — 409 Conflict: Returned when the station is at capacity (all MaxParallelExecutions slots in use). Response body contains activeCount, maxParallel, activeExecutionIds and activeExecutions (slot, execution id, test name, serial number and step progress of each run holding a slot). Wait for a slot to free up, or call abort_test on a running execution. A 409 is also returned when MES rejects the start; its message says so, and waiting does not help.

Note: The executionId in the response is the GUID you pass to all other execution tools (get_test_status, abort_test, get_execution_log, etc.).

get_test_status

Returns the current status and header details of a test execution.

Returns: result — full TestResultDetailDto including verdict, stepCount, child executions, artifacts; waitingForOperator (bool) and pendingPrompt — while the run is going, the operator prompt it is blocked on (promptId, stepName, title, message, buttons[], input, timeout; see tools-prompts.md), or null

Calls: GET /api/test-results/{id}, and GET /api/testexecution/{id}/prompt while the run has not ended

A run blocked on a prompt looks exactly like a slow step from its status alone. If waitingForOperator is true, the run will not move until somebody answers — at the station, or with answer_prompt.

abort_test

Signals the running test executor to stop at the next safe point.

Returns: message confirming the abort signal was sent

Calls: POST /api/testexecution/{executionId}/abort

Note: Abort is asynchronous. The execution transitions to ABORTED verdict after the current step finishes. Poll get_test_status to confirm.

wait_for_test_completion

Polls a test execution until it reaches a terminal state, then returns the full result. Use this instead of repeatedly calling get_test_status manually.

Returns: result — same as get_test_status once the execution is complete

Throws: TimeoutException if the execution does not complete within timeoutSeconds

list_available_tests

Lists all YAML test files available from installed (activated) packages.

Returns: tests[] — each item has packageName, testName, filePath, requiredTags

Calls: GET /api/packages/test-files

validate_yaml

Validates YAML test content without executing it. Use before committing a new test.

Returns: validation.isValid (bool), validation.errors[] — each error has a message and line number

Calls: POST /api/yaml/validate

get_execution_log

Returns log messages for a test execution as a flat list of strings.

Returns: logs[] — plain message strings in chronological order

Calls: GET /api/test-results/{id}/logs

To get structured log entries (with timestamps, step names, log levels), use get_execution_logs in tools-reports.md instead.

check_mes_routing

Queries the MES for routing information for a serial number. Tells you whether testing is allowed on this station and which test options are available.

Returns: routing.isKnown, routing.options[], routing.rejectionReason (if blocked)

Calls: GET /api/mes/routing?serialNumber={sn}

When the station is not connected to a real MES, the API uses AllowAllMesService which returns isKnown: true with an empty options list. Testing is always allowed.