The Operator UI page is blank or never opens

Three usual causes. (1) The test finished before the browser loaded: keep the process alive by looping test.execute() inside the StationServer block, as frontend_example.py does. (2) Port mismatch: CONF.load(station_server_port='4444') must match the URL passed to web_launcher.launch(). (3) A tornado version above 6.4 installed in the same environment; pin tornado<6.5. If the page loads but shows no station, click Refresh Station.

My test fails but every measurement I set is within limits

A measurement declared with @htf.measures but never assigned has outcome UNSET, which fails the phase. Run with console_summary.ConsoleSummary() to see 'failed_item: (Outcome.UNSET)'. Either set it in every code path, or set the configuration key allow_unset_measurements to true.

Why is the outcome ERROR instead of FAIL?

ERROR means an unhandled exception ended the test — a problem with the test or the fixture, not a judgement on the DUT. FAIL means a measurement failed validation or a phase returned STOP/FAIL_AND_CONTINUE. If certain exceptions do mean the DUT is bad (a timeout waiting for it to boot), list them in test.configure(failure_exceptions=[...]) and the outcome becomes FAIL.

What is the difference between PhaseResult.SKIP and run_if?

run_if=lambda: False prevents the phase from running at all and leaves no trace in the record. Returning PhaseResult.SKIP from inside the phase records the phase with outcome SKIP and ignores its measurements. Use run_if for station-level switches and SKIP for decisions that depend on earlier results.

A phase times out even though I am debugging it

timeout_s still applies under the debugger. When you set run_under_pdb=True, raise timeout_s as well, or remove it while debugging.

How do I stop the whole test on the first failure?

test.configure(stop_on_first_failure=True), or the configuration key stop_on_first_failure: true. For selective stops — only before an expensive phase — use checkpoints.checkpoint() instead.

How do I retry a flaky phase?

Return PhaseResult.REPEAT from the phase and cap it with @htf.PhaseOptions(repeat_limit=3). To retry automatically when a measurement fails validation, add repeat_on_measurement_fail=True. See the repeat example.

Measurement names with dots or dashes raise an error

Measurement names must be valid Python identifiers because they are accessed as attributes (test.measurements.name). Use underscores: 'vbat_mv', not 'vbat-mv' or 'vbat.mv'. With with_args templates, the rule applies after substitution.

Can two phases declare the same measurement name?

Yes, measurements belong to their phase, so the record keeps both. It is discouraged because tools that flatten measurements per run cannot tell them apart. Prefix the name with the phase or stage instead.

How do I pass a value from one phase to the next?

Read the earlier measurement: test.get_measurement('voltage').value. For arbitrary state, store it on a plug (plugs are instantiated once per test and shared by all phases) or in test.test_record.metadata.

Where does the JSON file go and why is it huge?

OutputToJSON writes to the pattern you give it, relative to the working directory. Attachments are inlined base64 by default; pass inline_attachments=False, or attach less. The JSON format reference lists every field.

How do I get results into a database instead of files?

Write an output callback: any callable taking a TestRecord, added with test.add_output_callbacks(). TofuPilot ships one (from tofupilot.openhtf import upload) that sends the record to a hosted workspace with yield and Cpk analytics; the same shape works for your own REST API or SQL insert.

Can I change the station_id?

Yes. It is a configuration key: --config-value station_id=EOL-01, a config file, or CONF.load(station_id='EOL-01') before execute(). It defaults to the hostname.

Why is the phase source code missing from the record?

capture_source defaults to false because copying every phase's source is slow and large. Set the configuration key capture_source: true to include it in code_info.

Which Python versions does OpenHTF support?

OpenHTF 1.6.x requires Python 3.10 or newer. 1.5.2 is the last release for Python 3.7–3.9 and is unmaintained.

Does OpenHTF work on Windows?

Yes. The framework, console output (via colorama) and Operator UI run on Windows, Linux and macOS. The USB plugs (ADB, Fastboot) need libusb and are easier on Linux.

Is OpenHTF still maintained?

Yes. A team at Waymo maintains it; 1.6.0 shipped in March 2025 and master continues to receive commits in 2026. See Releases.

Is OpenHTF related to TofuPilot?

No. OpenHTF is Google's framework, Apache 2.0, maintained at Waymo. TofuPilot is an independent company that runs this documentation site and sells a database and analytics product that accepts OpenHTF records through an output callback. You can use OpenHTF without TofuPilot.

Can I use OpenHTF with pytest?

They solve different problems. pytest runs assertions across many test functions; OpenHTF runs one DUT through a sequence and records measurements. Teams sometimes use pytest to unit-test their plugs and OpenHTF for the station test. See OpenHTF vs pytest.

OpenHTF FAQ and Troubleshooting

Answers to common OpenHTF questions and errors — blank Operator UI, unset measurements failing, ERROR vs FAIL outcomes, phase timeouts, tornado version conflicts, Python support, and how OpenHTF relates to TofuPilot.

Questions that come up on Discord and in the GitHub issues, with the shortest working answer. Install-time errors are on the Installation page.

FAQ and Troubleshooting

Running tests

Output and data

Compatibility

Still stuck?

Installation problems

Test Options

Community

On this page