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(-) diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index 6842533e2c6..d322cf60e26 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -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? -------------------------- diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst index d8c3cbf496c..a26ee6ad7de 100644 --- a/doc/usage/cmd/ut.rst +++ b/doc/usage/cmd/ut.rst @@ -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 -- 2.43.0