diff options
Diffstat (limited to 'docs/unit_tests.md')
| -rw-r--r-- | docs/unit_tests.md | 88 |
1 files changed, 50 insertions, 38 deletions
diff --git a/docs/unit_tests.md b/docs/unit_tests.md index 898c682fda..eeb618fbb7 100644 --- a/docs/unit_tests.md +++ b/docs/unit_tests.md @@ -30,9 +30,20 @@ Build and run all unit tests: Unit tests live in the [`test`] subdirectory of the CrOS EC codebase. -Existing EC unit tests will use the EC Test API, including test-related macros -(e.g., `TEST_EQ`, `TEST_NE`) and functions defined in [`test_util.h`]. Note -the `EC_TEST_RETURN` return type on the functions that are test cases. +All new unit tests should be written to use the Zephyr Ztest +[API](https://docs.zephyrproject.org/latest/guides/test/ztest.html). +If you are making significant changes to an existing test, you should also +look at porting the test from the EC test API to the Ztest API. + +Using the Ztest API makes the unit tests suitable for submitting upstream to +the Zephyr project, and reduces the porting work when the EC transitions to +the Zephyr RTOS. + +### File headers + +Include [`test_util.h`] and any other required includes. In this example, +the function being tested is defined in the test, but a real unit test would +include the header file for the module that defines `some_function`. `test/my_test.c`: @@ -44,7 +55,17 @@ static bool some_function(void) { return true; } +``` + +[`test_util.h`] includes `ztest.h` if `CONFIG_ZEPHYR` is defined, +or defines a mapping from the `zassert` macros to the EC +`TEST_ASSERT` macros if `CONFIG_ZEPHYR` is not defined. +### Test cases + +Define the test cases. Use the `EC_TEST_RETURN` return type on these functions. + +```c /* Write a function with the following signature: */ test_static EC_TEST_RETURN test_my_function(void) { @@ -52,26 +73,15 @@ test_static EC_TEST_RETURN test_my_function(void) bool condition = some_function(); /* Check that the expected condition is correct. */ - TEST_EQ(condition, true, "%d"); + zassert_true(condition, NULL); return EC_SUCCESS; } ``` -New unit tests or significant changes to existing tests should use the Zephyr -Ztest [API](https://docs.zephyrproject.org/latest/guides/test/ztest.html). - `test/my_test.c`: ```c -#include <stdbool.h> -#include "test_util.h" - -static bool some_function(void) -{ - return true; -} - /* Write a function with the following signature: */ test_static EC_TEST_RETURN test_my_function(void) { @@ -79,43 +89,30 @@ test_static EC_TEST_RETURN test_my_function(void) bool condition = some_function(); /* Check that the expected condition is correct. */ - zassert_true(condition, NULL); + TEST_EQ(condition, true, "%d"); return EC_SUCCESS; } ``` -Note that the only difference between those two versions of `test/my_test.c` -is the assertion: +The only difference between those two versions of `test/my_test.c` is the +assertion: ```c - TEST_EQ(condition, true, "%d"); + zassert_true(condition, NULL); ``` versus ```c - zassert_true(condition, NULL); + TEST_EQ(condition, true, "%d"); ``` -Currently, these tests using the Ztest API are still built with the EC test -framework. [`test_util.h`] defines a mapping from the `zassert` macros to the -EC `TEST_ASSERT` macros when `CONFIG_ZEPHYR` is not `#define`'d. - -Even though the tests are currently compiled only to the EC test framework, -developers should still target the Ztest API for new unit tests. Future work -will support building directly with the Ztest API. This makes the unit tests -suitable for submitting upstream to the Zephyr project, and reduces the -porting work when the EC transitions to the Zephyr RTOS. Similarly, when -a development makes significant modifications to an existing unit test, they -should consider porting the test to the Ztest API as part of the modifications. - -See [chromium:2492527](https://crrev.com/c/2492527) for a simple example of -porting an EC unit test to the Ztest API. - -`test/my_test.c`: +### Specify the test cases to run The EC test API enumerates the test cases using `RUN_TEST` in the `run_test` function, while the Ztest API enumerates the test cases using `ztest_unit_test` inside another macro for the test suite, inside of `test_main`. +`test/my_test.c`: + ```c #ifdef CONFIG_ZEPHYR void test_main(void) @@ -137,6 +134,12 @@ void run_test(int argc, char **argv) #endif /* CONFIG_ZEPHYR */ ``` +### Task List + +EC unit tests can run additional tasks besides the main test thread. The EC unit +test implementation provides a phtreads-based implementation of the EC task API. +We do not yet support running additional tasks in Ztest-based tests. + In the [`test`] subdirectory, create a `tasklist` file for your test that lists the tasks that should run as part of the test: @@ -149,7 +152,9 @@ the tasks that should run as part of the test: #define CONFIG_TEST_TASK_LIST ``` -Add the test to the `Makefile`: +### Makefile + +Add the test to the `Makefile` so that it can build as an EC unit test: `test/build.mk`: @@ -171,12 +176,18 @@ host-my_test run-my_test ``` -Build and run the test: +### Build and Run + +Build and run the test as an EC unit test: ```bash (chroot) $ make run-my_test ``` +For building the test as a Zephyr Ztest unit test, follow the instructions in +[Porting EC unit tests to Ztest](./ztest.md) to build the unit test for +Zephyr's "native_posix" host-based target. + *** note **TIP**: Unit tests should be independent from each other as much as possible. This keeps the test (and any system state) simple to reason about and also @@ -186,6 +197,7 @@ allows running unit tests in parallel. You can use the ## Mocks +We do not yet support mocks for Zephyr Ztest-based tests. [Mocks][`mock`] enable you to simulate behavior for parts of the system that you're not directly testing. They can also be useful for testing specific edge cases that are hard to exercise during normal use (e.g., error conditions). |