diff --git a/developer_guides/index.rst b/developer_guides/index.rst index 5ac976e5..c6f605a6 100644 --- a/developer_guides/index.rst +++ b/developer_guides/index.rst @@ -11,6 +11,7 @@ terminology before reading further. introduction firmware/index + unit_tests_ztest unit_tests xtrun/index topology/topology diff --git a/developer_guides/unit_tests.rst b/developer_guides/unit_tests.rst index 93e0e0e7..2bf6eeb6 100644 --- a/developer_guides/unit_tests.rst +++ b/developer_guides/unit_tests.rst @@ -1,7 +1,16 @@ .. _unit_tests: -Unit Tests -########## +Unit Tests (Legacy CMocka) +########################### + +.. warning:: + **DEPRECATED: This documentation describes the legacy CMocka-based unit testing framework.** + + SOF is migrating to Zephyr's native ztest framework. The CMocka tests are being phased out + and will be removed once the migration is complete. + + **For new unit tests, please use the ztest framework.** See :doc:`unit_tests_ztest` for + the current testing approach. Prerequisites ************* diff --git a/developer_guides/unit_tests_ztest.rst b/developer_guides/unit_tests_ztest.rst new file mode 100644 index 00000000..8e049758 --- /dev/null +++ b/developer_guides/unit_tests_ztest.rst @@ -0,0 +1,101 @@ +.. _unit_tests_ztest: + +Unit Tests with Ztest +###################### + +Overview +******** + +The SOF project is transitioning from CMocka to Zephyr's native ztest framework for unit testing. This migration aligns SOF's testing infrastructure with the Zephyr RTOS ecosystem and provides better integration with Twister test runner. + +The migration from CMocka to ztest is ongoing. Currently, basic unit tests (math functions, library functions) have been migrated, with more complex audio component tests in progress. For the latest migration status, see `GitHub issue #10110 `_. + +For more information about the ztest framework, refer to `Zephyr's ztest documentation `_. + +For legacy CMocka-based unit tests, refer to :doc:`unit_tests`. + +Prerequisites +************* + +This guide assumes that you have a basic SOF development environment set up. If not, follow the instructions at :doc:`../getting_started/build-guide/build-with-zephyr` first. + +Required Tools +============== + +Ztest unit tests require the following tools and dependencies: + +.. code-block:: bash + + sudo apt-get update + sudo apt-get install -y clang llvm ninja-build device-tree-compiler \ + python3-pyelftools gcc-multilib g++-multilib + +West Meta-Tool +============== + +Zephyr uses the ``west`` meta-tool for project management. Install it using pip: + +.. code-block:: bash + + pip3 install west + +Python Dependencies +=================== + +Install Zephyr's Python requirements: + +.. code-block:: bash + + cd path/to/zephyrproject/zephyr + pip3 install -r scripts/requirements.txt + +Building and Running Tests +*************************** + +Setup Workspace +=============== + +First, initialize your workspace with west if you haven't already: + +.. code-block:: bash + + cd path/to/sof + west init -l + west update --narrow --fetch-opt=--filter=tree:0 + +Set Toolchain +============= + +Ztest unit tests use the LLVM/Clang toolchain: + +.. code-block:: bash + + export ZEPHYR_TOOLCHAIN_VARIANT=llvm + +Running Unit Tests +================== + +To build and run all unit tests using Twister: + +.. code-block:: bash + + west twister --testsuite-root sof/test/ztest/unit/ --platform native_sim \ + --verbose --inline-logs + +Twister provides detailed test results in the console output. Test results are also saved in ``twister-out/`` directory. + +Writing a Unit Test +******************* + +*This section is in progress and will be added in a future update.* + +Test Architecture +***************** + +*This section is in progress and will be added in a future update.* + +Notes +***** + +*This section is in progress and will be added in a future update.* + diff --git a/developer_guides/xtrun/index.rst b/developer_guides/xtrun/index.rst index f48930ff..cbbc1fc1 100644 --- a/developer_guides/xtrun/index.rst +++ b/developer_guides/xtrun/index.rst @@ -55,6 +55,10 @@ intrinsics (such as HiFi3) in your C programs. Unit tests ********** +.. note:: + **This section describes legacy CMocka-based unit tests.** SOF is migrating to Zephyr's + ztest framework. For current unit testing practices, see :doc:`../unit_tests_ztest`. + In the SOF project, ``xt-run`` is used as the executor for unit tests. The below example shows how you can add a simple unit test case for a sample