From dcc8b7c98f5414403e76e998df27d54a7cccd5da Mon Sep 17 00:00:00 2001 From: Tomasz Leman Date: Mon, 17 Nov 2025 15:15:22 +0100 Subject: [PATCH 1/2] unit_tests: Add ztest documentation structure and mark CMocka as legacy Prepare documentation for the ongoing migration from CMocka to Zephyr's native ztest framework for SOF unit tests. Changes: - Create new unit_tests_ztest.rst placeholder for upcoming ztest documentation - Add deprecation notice to unit_tests.rst indicating CMocka is legacy - Add informational note to xtrun/index.rst about the testing framework transition - Update developer_guides/index.rst to include new ztest documentation entry The CMocka-based tests are being phased out as part of the migration to ztest. This commit adds notices to inform developers that new tests should use ztest, while existing CMocka documentation remains available during the transition period. The new ztest documentation page is positioned before the legacy CMocka documentation in the index for better discoverability. Related: thesofproject/sof#10110 Signed-off-by: Tomasz Leman --- developer_guides/index.rst | 1 + developer_guides/unit_tests.rst | 13 +++++++++++-- developer_guides/unit_tests_ztest.rst | 5 +++++ developer_guides/xtrun/index.rst | 4 ++++ 4 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 developer_guides/unit_tests_ztest.rst 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..c96bdd96 --- /dev/null +++ b/developer_guides/unit_tests_ztest.rst @@ -0,0 +1,5 @@ +.. _unit_tests_ztest: + +Unit Tests with Ztest +###################### + 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 From 58d96774645d5e455c563dce52b56fb481f275d6 Mon Sep 17 00:00:00 2001 From: Tomasz Leman Date: Mon, 17 Nov 2025 16:11:34 +0100 Subject: [PATCH 2/2] unit_tests: Add initial ztest documentation with setup and build instructions Add initial documentation for SOF's new ztest-based unit testing framework. This provides developers with essential information to get started with ztest while the migration from CMocka is ongoing. Content includes: - Overview of ztest migration and current status - Prerequisites and required tools - Step-by-step workspace setup with west - Instructions for building and running tests with Twister - Placeholders for future sections (writing tests, architecture, notes) Related: thesofproject/sof#10110 Signed-off-by: Tomasz Leman --- developer_guides/unit_tests_ztest.rst | 96 +++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/developer_guides/unit_tests_ztest.rst b/developer_guides/unit_tests_ztest.rst index c96bdd96..8e049758 100644 --- a/developer_guides/unit_tests_ztest.rst +++ b/developer_guides/unit_tests_ztest.rst @@ -3,3 +3,99 @@ 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.* +