| .. _testing: |
| |
| Test Framework |
| ############### |
| |
| The Zephyr Test Framework (Ztest) provides a simple testing framework intended |
| to be used during development. It provides basic assertion macros and a generic |
| test structure. |
| |
| The framework can be used in two ways, either as a generic framework for |
| integration testing, or for unit testing specific modules. |
| |
| Quick start - Integration testing |
| ********************************* |
| |
| A simple working base is located at :file:`samples/testing/integration`. Just |
| copy the files to ``tests/`` and edit them for your needs. The test will then |
| be automatically built and run by the sanitycheck script. If you are testing |
| the **bar** component of **foo**, you should copy the sample folder to |
| ``tests/foo/bar``. It can then be tested with:: |
| |
| ./scripts/sanitycheck -s tests/foo/bar/test |
| |
| The sample contains the following files: |
| |
| CMakeLists.txt |
| |
| .. literalinclude:: ../../../samples/testing/integration/CMakeLists.txt |
| :language: CMake |
| :linenos: |
| |
| sample.yaml |
| |
| .. literalinclude:: ../../../samples/testing/integration/sample.yaml |
| :language: yaml |
| :linenos: |
| |
| prj.conf |
| |
| .. literalinclude:: ../../../samples/testing/integration/prj.conf |
| :language: text |
| :linenos: |
| |
| src/main.c |
| |
| .. literalinclude:: ../../../samples/testing/integration/src/main.c |
| :language: c |
| :linenos: |
| |
| .. contents:: |
| :depth: 1 |
| :local: |
| :backlinks: top |
| |
| Quick start - Unit testing |
| ************************** |
| |
| Ztest can be used for unit testing. This means that rather than including the |
| entire Zephyr OS for testing a single function, you can focus the testing |
| efforts into the specific module in question. This will speed up testing since |
| only the module will have to be compiled in, and the tested functions will be |
| called directly. |
| |
| Since you won't be including basic kernel data structures that most code |
| depends on, you have to provide function stubs in the test. Ztest provides |
| some helpers for mocking functions, as demonstrated below. |
| |
| In a unit test, mock objects can simulate the behavior of complex real objects |
| and are used to decide whether a test failed or passed by verifying whether an |
| interaction with an object occurred, and if required, to assert the order of |
| that interaction. |
| |
| The :file:`samples/testing/unit` folder contains an example for testing |
| the net-buf api of Zephyr. |
| |
| CMakeLists.txt |
| |
| .. literalinclude:: ../../../samples/testing/unit/CMakeLists.txt |
| :language: CMake |
| :linenos: |
| |
| sample.yaml |
| |
| .. literalinclude:: ../../../samples/testing/unit/sample.yaml |
| :language: yaml |
| :linenos: |
| |
| main.c |
| |
| .. literalinclude:: ../../../samples/testing/unit/main.c |
| :language: c |
| :linenos: |
| |
| API reference |
| ************* |
| |
| Running tests |
| ============= |
| |
| .. doxygengroup:: ztest_test |
| :project: Zephyr |
| |
| Assertions |
| ========== |
| |
| These macros will instantly fail the test if the related assertion fails. |
| When an assertion fails, it will print the current file, line and function, |
| alongside a reason for the failure and an optional message. If the config |
| option:`CONFIG_ZTEST_ASSERT_VERBOSE` is 0, the assertions will only print the |
| file and line numbers, reducing the binary size of the test. |
| |
| Example output for a failed macro from |
| ``zassert_equal(buf->ref, 2, "Invalid refcount")``: |
| |
| .. code-block:: none |
| |
| Assertion failed at main.c:62: test_get_single_buffer: Invalid refcount (buf->ref not equal to 2) |
| Aborted at unit test function |
| |
| .. doxygengroup:: ztest_assert |
| :project: Zephyr |
| |
| Mocking |
| ======= |
| |
| These functions allow abstracting callbacks and related functions and |
| controlling them from specific tests. You can enable the mocking framework by |
| setting :option:`CONFIG_ZTEST_MOCKING` to "y" in the configuration file of the |
| test. The amount of concurrent return values and expected parameters is |
| limited by :option:`CONFIG_ZTEST_PARAMETER_COUNT`. |
| |
| Here is an example for configuring the function ``expect_two_parameters`` to |
| expect the values ``a=2`` and ``b=3``, and telling ``returns_int`` to return |
| ``5``: |
| |
| .. literalinclude:: mocking.c |
| :language: c |
| :linenos: |
| |
| .. doxygengroup:: ztest_mock |
| :project: Zephyr |