doc/subsystems/test/ztest.rst

.. _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:

Makefile

.. literalinclude:: ../../../samples/testing/integration/Makefile
   :language: Make
   :linenos:

sample.yaml

.. literalinclude:: ../../../samples/testing/integration/sample.yaml
   :language: yaml
   :linenos:

prj.conf

.. literalinclude:: ../../../samples/testing/integration/prj.conf
   :language: text
   :linenos:

src/Makefile

.. literalinclude:: ../../../samples/testing/integration/src/Makefile
   :language: Make
   :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.

Makefile

.. literalinclude:: ../../../samples/testing/unit/Makefile
   :language: Make
   :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