Phases

Last updated on November 19, 2026

A phase represents a single step within your test procedure. A group of phases that several procedures share is written once as a sequence and called with uses:.

Runtime

Each phase can run Python scripts, execute a command, and/or display operator UI prompts. Find usage and example for Python, shell commands and operator UI.

Name

You can create a new phase by adding it to the main list.

main:
  - name: Power On Test

TofuPilot will automatically trim whitespace and enforce a 100 character limit.

Description

You can add an optional description to explain what the phase does.

main:
  - name: Power On Test
    description: "Verify 5V power rail is within specification"

TofuPilot will enforce a 1,000 character limit on descriptions.

Key

You can define a key for referencing this phase in your Python phases or YAML procedure.

main:
  - name: Power On Test
    description: "Verify 5V power rail is within specification"
    key: power_on_test

If not specified, TofuPilot auto-generates a key from the phase name. Keys must be valid Python identifiers: start with a letter or underscore, followed by letters, numbers, or underscores.

With

You can pass keyword arguments to a Python phase's function with with:. One function can then serve several phases.

main:
  - name: Check 3V3 Rail
    key: rail_3v3
    python: phases.rails:check_rail
    with: 
      channel: 1
      nominal: 3.3
  - name: Check 5V Rail
    key: rail_5v
    python: phases.rails:check_rail
    with: 
      channel: 2
      nominal: 5.0
def check_rail(dmm, measurements, channel, nominal): 
    measurements.voltage = dmm.read_voltage(channel)

The procedure fails to load when a with: key is not a parameter of the function (unless it takes **kwargs), when a parameter without a default is left unfilled, or when a key names a parameter TofuPilot already fills: an injected one (phase, run, measurements, log, ui, unit, attach, dashboard, inputs, config, secrets), a plug key or a phase key. with: needs python:: an executable phase has no function to receive it.

Values can hold {config.X}, {secrets.X} and {run.*} markers, resolved for each slot when the run starts. A phase can also set environment variables while it runs with env:, Python and executable phases alike.

Timeout

You can set a maximum duration for the phase with timeout: 90s. When it elapses, the phase ends with the TIMEOUT outcome. Without it, the phase has no time limit. See Timeout for the duration syntax, bounds, and per-runtime behavior.

Outcome

Your phase can end with one of these outcomes:

OutcomeIf
ERRORUnhandled exception thrown
SKIPCalled phase.skip() or phase skipped by framework
TIMEOUTPhase exceeded timeout limit
ABORTEDCalled phase.stop(), or the run was stopped by the operator while the phase was running (STOP in the console and --json)
FAILCalled phase.fail(), phase.retry() exceeding retry limit, or measurements invalid
PASSAll measurements valid

A stopped phase reads STOP in the console and in the --json events, and the run reads ABORTED. The uploaded run has no stop outcome for a phase: it records the phase as FAIL.

Outcome Control

You can control phase outcomes by calling methods on the phase parameter in your python function :

MethodDescription
phase.fail()Mark phase as fail and exit immediately
phase.skip()Skip this phase
phase.retry()Retry this phase (see Retry)
phase.stop()Stop the slot this phase runs in: its remaining phases are skipped, its teardown runs. With a single slot, that is the whole run. Other slots continue.

For example, you can skip a phase when a precondition is not met:

def advanced_calibration(phase, device):
    if not device.supports_advanced_mode():
        phase.skip() 

    # Phase continues if not skipped

Outcome Resolution

TofuPilot evaluates outcomes in priority order (first match wins):

"Run already stopping?" means a stop (the operator, Ctrl-C, a signal, abort_run) cut this phase while it was in flight: the phase then reads ABORTED, even if it raised while being cut off. A timeout that elapsed first still reads TIMEOUT. A teardown phase is the exception and keeps its own outcome, since it runs because of the stop. A failed sibling does not cut a phase in flight: it finishes and keeps its own outcome, and only the phases not started yet are skipped. A phase.retry() whose next attempt a failed sibling or a stop cancelled reads RETRY in phase_finished and run_summary, and is not counted among the failed phases.

A failed measurement takes precedence over phase.skip() and phase.stop(): a phase that records an out-of-limit value and then calls either ends FAIL, so the defective unit counts as a failure. The stop is still honoured: the slot ends there. Call phase.skip() before recording measurements if the phase must not count.

Fail or Raise

A phase that detects a defect in the unit should call phase.fail(). An uncaught exception means the test itself could not run, and ends the phase ERROR.

You writeOutcomeUse it when
phase.fail("No heartbeat after 10 s")FAILThe unit did not meet the test: no response, wrong value, wrong direction
raise RuntimeError(...) or an uncaught exceptionERRORThe bench or the test code is at fault: instrument missing, bad configuration, bug

Both outcomes go through on_first_failure and can be mapped separately with then, for example then: fail: retry without retrying on errors. A wait on the unit that expires (a heartbeat, a sensor reading, a power-up) is usually a unit failure: catch it and call phase.fail() rather than letting it raise.

phase.fail(), phase.skip(), phase.retry() and phase.stop() all exit the function immediately, and accept an optional message. The message is written to the phase logs and becomes the phase's message without changing its outcome: the operator sees the first failing phase's message on the FAIL screen, tofupilot run --json sends it as the error of the phase's phase_finished event, and the uploaded run stores it with the phase (up to 49,000 characters). A phase function must not return a value: to pass, return normally.

After the outcome is determined, TofuPilot moves to the Next Action.

Example

Let's create a battery test with 2 phases:

  1. Test power that succeeds
  2. Test capacity that fails

We'll create the procedure file and the Python modules:

procedure.yaml
test_power.py
test_capacity.py

We'll define the phases and reference the modules:

def test_power(phase, battery):
    if not battery.check_voltage():
        phase.fail()
    # Implicit pass
def test_capacity(phase, battery):
    if not battery.verify_capacity():
        phase.fail()
    # Implicit pass
name: Battery Functional Test

plugs:
  - key: battery
    name: Battery Tester
    python: plugs.battery:Battery

main:
  - name: Test Power
    python: phases.test_power

  - name: Test Capacity
    python: phases.test_capacity

TofuPilot executes both phases in parallel:

Previous Results

A phase can access measurements, outcome, and duration from a previously completed phase. Name a function parameter after the phase's key, and TofuPilot injects a read-only result object.

Name the referenced phase in depends_on. A phase only receives the results of its declared dependencies (directly or through a chain of depends_on) and of phases from an earlier stage (shared setup for a per-slot setup phase, setup for a main phase, setup and main for a teardown phase). Naming any other phase fails the phase with an error that points to depends_on, whatever the scheduling order.

Changed in CLI 1.7.18. Before, a phase received the result of any phase that happened to be complete, so reading a sibling without depends_on worked under workers: 1 and failed under parallel workers. Procedures that relied on that must add the depends_on entry.

Example

A measure_voltage phase records a voltage measurement, then a verify_voltage phase reads it using the phase key:

procedure.yaml
measure_voltage.py
verify_voltage.py
main:
  - name: Measure Voltage
    key: measure_voltage
    python: phases.measure_voltage
    measurements:
      - name: voltage
        key: voltage

  - name: Verify Voltage
    key: verify_voltage
    python: phases.verify_voltage
    depends_on:
      - measure_voltage
def measure_voltage(measurements):
    measurements.voltage = 5.03
def verify_voltage(phase, measure_voltage): 
    voltage = measure_voltage.voltage 
    if voltage < 4.9 or voltage > 5.1:
        phase.fail()

If you don't specify a key, it is auto-generated from the phase name (e.g., "Measure Voltage" becomes measure_voltage).

Available Properties

PropertyDescription
<phase_key>.<measurement_name>Value of a recorded measurement
<phase_key>.outcomePhase outcome ("pass", "fail", etc.)
<phase_key>.duration_msPhase execution time in milliseconds

In multi-slot runs, a phase can only access results from phases within the same slot.

Previous results are the way to pass data from one phase to the next. run.metadata is not shared: each phase receives an empty run.metadata, and what a phase writes there is merged into the report but never read back by later phases. A module-level variable does not work either, since phases can run in separate worker processes. A phase file is run fresh for every phase it serves, so its module state starts over; a module of a package you wrote as one (an __init__.py in every folder up to the procedure root) is imported once per worker, as Python imports it, and imported again when one of its files changes.

Previous Attempt

A retried phase can read the result of its own previous attempt. Name a parameter after the phase's own key, with a default of None: the first attempt has no previous result and receives None.

def motor_b(phase, run, measurements, motor_b=None): 
    if motor_b is not None and motor_b.outcome == "fail": 
        if getattr(motor_b, "direction", None) == "reversed": 
            reverse_esc_direction() # adapt the retry to what failed
    measurements.direction = measure_direction()

Without the default, the first attempt fails with a "required parameter could not be resolved" error.

The parameter holds the attempt just before this one only, not the whole history, and only the measurements that attempt recorded. An attempt that failed before recording anything leaves only outcome and duration_ms, so read measurements with getattr(..., None). To keep state across several retries, record it as a measurement on every attempt. run.retry.count gives the attempt number (0 for the first attempt) and run.retry.limit the configured limit. The older run.retry_count and run.retry_limit still work.

Next Action

After determining the phase outcome, TofuPilot decides the next action. You can customize the default behavior at procedure level or at phase level.

Actions

ActionDescription
continueContinue to next phase
stopStop entire run
retryRetry this phase (see Retry)

Default

OutcomeNext Action
PASScontinue to next phase
FAILstop entire run, or continue with on_first_failure: continue (see On Fail)
SKIPcontinue to next phase
ERRORSame as fail: follows on_first_failure
TIMEOUTSame as fail: follows on_first_failure
ABORTEDstop entire run

Per-phase Override

Use the then field to override the default action for a specific phase. Map any of pass, fail, error, timeout to one of the actions above. An outcome left out of then keeps its default.

KeyApplies whenDefault
passThe phase passedcontinue
failA measurement failed its validators, or the phase called phase.fail()on_first_failure (stop unless set to continue)
errorThe phase raised an uncaught exceptionon_first_failure
timeoutThe phase exceeded its timeouton_first_failure

SKIP always continues and ABORTED always stops: neither can be mapped. A then entry takes precedence over on_first_failure for that phase. retry reruns the phase within its retry limit; see When Retries Run Out for what follows the last attempt.

For example, if on_first_failure: stop globally but you want execution to continue past a non-critical phase that errors:

execution:
  on_first_failure: stop

plugs:
  - key: sensor
    name: Sensor
    python: plugs.sensor:Sensor

main:
  - name: Diagnostic Check
    python: diagnostic_check
    then: 
      error: continue
      fail: continue
  - name: Final Report
    python: final_report
    depends_on:
      - diagnostic_check
def diagnostic_check(phase, sensor):
    reading = sensor.read()
    if reading is None:
        phase.fail("Sensor returned no data")
    if reading < 0:
        raise ValueError(f"Invalid sensor reading: {reading}")

How is this guide?

On this page