diff mbox series

[Concept,8/9] doc: ut: Document return value

Message ID 20251229160611.3899708-9-sjg@u-boot.org
State New
Headers
Series test: Various improvements to unit-test infrastructure |

Commit Message

Simon Glass Dec. 29, 2025, 4:06 p.m. UTC 
  From: Simon Glass <simon.glass@canonical.com>

Add documentation for the return value of the ut command:
- Returns 0 on success if all tests pass
- Returns 1 on failure if any test fails
- Skipped tests do not cause a failure

Also explain when tests may be skipped and how to detect skipped tests
programmatically using the -E flag.

Co-developed-by: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>
---

 doc/usage/cmd/ut.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
diff mbox series

Patch

diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst
index c40928dece9..731579e5b1d 100644
--- a/doc/usage/cmd/ut.rst
+++ b/doc/usage/cmd/ut.rst
@@ -84,6 +84,23 @@  To specify a list of suites to run, <suites> can also be a comma-separated list.
 See :ref:`develop/tests_writing:writing c tests` for more information on how to
 write unit tests.
 
+Return Value
+------------
+
+The `ut` command returns 0 (success) if all tests pass, or 1 (failure) if any
+test fails.
+
+Skipped tests do not cause a failure return. Tests may be skipped for several
+reasons:
+
+- Manual tests (with `_norun` suffix) are skipped unless `-f` or `-m` is used
+- Tests requiring features not available on the current platform (e.g.,
+  `UTF_OTHER_FDT` on non-sandbox, console recording disabled)
+- Tests that explicitly request to be skipped by returning `-EAGAIN`
+
+To detect skipped tests programmatically, use the `-E` flag and check for
+`Result: SKIP:` lines in the output.
+
 ut all
 ~~~~~~