121 lines
3.6 KiB
ReStructuredText
121 lines
3.6 KiB
ReStructuredText
.. _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.
|
|
|
|
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
|