From: Simon Glass <simon.glass@canonical.com>
Add a description of how test parameters work. This helps to make it
easier to write C tests which need setup to be done in Python.
Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>
---
doc/develop/tests_writing.rst | 41 +++++++++++++++++++++++++++++++++++
doc/usage/cmd/ut.rst | 11 ++++++++--
2 files changed, 50 insertions(+), 2 deletions(-)
@@ -101,6 +101,47 @@ constructs, in this case to check that the expected things happened in the
Python test.
+Passing arguments to C tests
+----------------------------
+
+Sometimes a C test needs parameters from Python, such as filenames or expected
+values that are generated at runtime. The test-argument feature allows this.
+
+Use the `UNIT_TEST_ARGS` macro to declare a test with arguments::
+
+ static int my_test_norun(struct unit_test_state *uts)
+ {
+ const char *filename = ut_str(0);
+ int count = ut_int(1);
+
+ /* test code using filename and count */
+
+ return 0;
+ }
+ UNIT_TEST_ARGS(my_test_norun, UTF_CONSOLE | UTF_MANUAL, my_suite,
+ { "filename", UT_ARG_STR },
+ { "count", UT_ARG_INT });
+
+Each argument definition specifies a name and type:
+
+- `UT_ARG_STR` - string argument, accessed via `ut_str(n)`
+- `UT_ARG_INT` - integer argument, accessed via `ut_int(n)`
+- `UT_ARG_BOOL` - boolean argument, accessed via `ut_bool(n)`
+ (use `1` for true, any other value for false)
+
+Arguments are passed on the command line in `name=value` format::
+
+ ut -f my_suite my_test_norun filename=/path/to/file count=42
+
+From Python, you can call the test like this::
+
+ cmd = f'ut -f my_suite my_test_norun filename={filepath} count={count}'
+ ubman.run_command(cmd)
+
+This approach combines Python's flexibility for setup (creating files,
+generating values) with C's speed and debuggability for the actual test logic.
+
+
How slow are Python tests?
--------------------------
@@ -11,7 +11,7 @@ Synopsis
::
- ut [-r<runs>] [-f] [-I<n>:<one_test>] [<suite> | all [<test>]] [<args>...]
+ ut [-r<runs>] [-f] [-R] [-I<n>:<one_test>] [<suite> | all [<test>]] [<args>...]
ut [-s] info
Description
@@ -37,10 +37,17 @@ test
causes another test to fail. If the one test fails, testing stops
immediately.
+-R
+ Preserve console recording on test failure. Normally when a test fails,
+ console recording is disabled so error messages go directly to output.
+ This flag keeps recording enabled, which is useful when testing the test
+ framework itself.
+
args
Optional arguments to pass to the test, in `name=value` format. These are
used by tests declared with `UNIT_TEST_ARGS()` which define expected
- argument names and types.
+ argument names and types. See :ref:`develop/tests_writing:passing arguments
+ to c tests` for details.
Typically the command is run on :ref:`arch/sandbox/sandbox:sandbox` since it
includes a near-complete set of emulators, no code-size limits, many CONFIG