product: maestro 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 accepts at most MaxParallelExecutions concurrent tests (default 1). By default a station runs a single test at a time. Calling start_test when the station is at capacity returns 409 Conflict ("Station at capacity").

If asked to run a test multiple times (e.g. "run 10 times and report the average"), run them sequentially unless you know the station allows parallelism:

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

On a parallel station (MaxParallelExecutions > 1) you may start additional tests up to the limit; each runs independently. Steps that share an instrument must declare requires: (see yaml/runtime-control.md).

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 and maxParallel. Wait for a slot to free up, or call abort_test on a running execution.

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

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

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.