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 TestTofuPilot 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_testIf 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.0def 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:
| Outcome | If |
|---|---|
| ERROR | Unhandled exception thrown |
| SKIP | Called phase.skip() or phase skipped by framework |
| TIMEOUT | Phase exceeded timeout limit |
| ABORTED | Called phase.stop(), or the run was stopped by the operator while the phase was running (STOP in the console and --json) |
| FAIL | Called phase.fail(), phase.retry() exceeding retry limit, or measurements invalid |
| PASS | All 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 :
| Method | Description |
|---|---|
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 skippedOutcome 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 write | Outcome | Use it when |
|---|---|---|
phase.fail("No heartbeat after 10 s") | FAIL | The unit did not meet the test: no response, wrong value, wrong direction |
raise RuntimeError(...) or an uncaught exception | ERROR | The 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:
- Test power that succeeds
- Test capacity that fails
We'll create the procedure file and the Python modules:
We'll define the phases and reference the modules:
def test_power(phase, battery):
if not battery.check_voltage():
phase.fail()
# Implicit passdef test_capacity(phase, battery):
if not battery.verify_capacity():
phase.fail()
# Implicit passname: 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_capacityTofuPilot 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:
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_voltagedef measure_voltage(measurements):
measurements.voltage = 5.03def 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
| Property | Description |
|---|---|
<phase_key>.<measurement_name> | Value of a recorded measurement |
<phase_key>.outcome | Phase outcome ("pass", "fail", etc.) |
<phase_key>.duration_ms | Phase 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
| Action | Description |
|---|---|
continue | Continue to next phase |
stop | Stop entire run |
retry | Retry this phase (see Retry) |
Default
| Outcome | Next Action |
|---|---|
| PASS | continue to next phase |
| FAIL | stop entire run, or continue with on_first_failure: continue (see On Fail) |
| SKIP | continue to next phase |
| ERROR | Same as fail: follows on_first_failure |
| TIMEOUT | Same as fail: follows on_first_failure |
| ABORTED | stop 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.
| Key | Applies when | Default |
|---|---|---|
pass | The phase passed | continue |
fail | A measurement failed its validators, or the phase called phase.fail() | on_first_failure (stop unless set to continue) |
error | The phase raised an uncaught exception | on_first_failure |
timeout | The phase exceeded its timeout | on_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_checkdef 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?