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

MCP Server — Unattended Mode

What Is Unattended Mode?

When a test is started by an AI assistant or an automated pipeline, there is no human operator watching the screen. If the test contains prompt steps (type: prompt in YAML) that normally require a button click or typed input, the execution blocks indefinitely waiting for a response that will never come.

Unattended mode solves this. When start_test is called with unattendedMode: true, the executor auto-responds to every prompt step using a deterministic rule instead of waiting for a human.

How to Enable It

Pass unattendedMode: true to the start_test tool:

start_test(
  yamlFilePath = "TestFiles/board-test.yaml",
  serialNumber = "UNIT-042",
  unattendedMode = true
)

This flag travels with the execution request and is stored for the lifetime of that execution. It has no effect on other concurrent or future executions.

How Prompt Steps Behave in Unattended Mode

Button prompts

When the executor reaches a type: prompt step with buttons, it selects a button automatically using this priority order:

The executor picks the first button (from the YAML definition order) whose action matches the highest-priority action found in the list. If the prompt has no buttons at all, a synthetic OK/Continue button is used.

The selected button and its action are recorded in the step's output variables (exec.prompt.response, exec.prompt.action) exactly as if a human had clicked it.

A warning log line is emitted for every auto-responded prompt:

[UNATTENDED] Auto-responding to prompt 'Inspect solder joints' with button 'OK' (action: Continue)

Value-input prompts

Some prompt steps include a text field where the operator must type a value (for example, a measured torque value or a calibration offset). These require special handling.

The failure message for a missing default is:

Unattended mode: prompt step 'Enter calibration offset' requires value input but no default is defined.

This is a deliberate forcing function — test developers who want their tests to be unattended-safe must declare defaults for all value-input prompts.

Making a Test Unattended-Safe

To guarantee a test runs to completion without human input:

1. Review all type: prompt steps in your YAML.

2. For button-only prompts: ensure the button list contains at least one button with action Continue or Pass. If your prompt only has a Fail or Abort button, the executor will auto-select it, which is probably not what you want. Add a Continue button to provide a safe path.

   - name: Inspect solder joints
     type: prompt
     prompt:
       message: "Visually inspect solder joints. Proceed if acceptable."
       buttons:
         - name: "Looks good"
           action: Continue    # ← unattended will pick this
         - name: "Fail — rework required"
           action: Fail
   

3. For value-input prompts: always declare an input.default:

   - name: Enter ambient temperature
     type: prompt
     prompt:
       message: "Enter the ambient temperature in °C."
       input:
         variable: ambient_temp
         default: "25"          # ← unattended uses this
         unit: "°C"
   

4. Validate with the validate_yaml tool or py validate.py before committing.

When NOT to Use Unattended Mode

The safest rule: only enable unattended mode for tests that have been run interactively at least once and reviewed for correctness. Mark them as unattended-safe in a comment in the YAML header once approved.

Interaction with Other Step Controls

Unattended mode only affects type: prompt steps. All other step types (type: runner, type: sequence, type: pattern, etc.) are unaffected.

Step-level controls (retry, precondition, run_on_abort, timeout_ms) all function normally in unattended mode. If a prompt step has a timeout_ms, the unattended auto-response happens immediately (zero delay) — the timeout is irrelevant but does not cause an error.

Output Variables Set by Unattended Prompt Steps

These variables are available to downstream steps via exec.* exactly as they would be after a human clicked a button: