mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-07 20:00:53 +00:00
add updates to some files in api guides
modified errors in making html add modifications based on the first review modified grammar problems of the original text
This commit is contained in:
Hao Ning
committed by
Krzysztof Budzynski
Krzysztof Budzynski
parent
0be0859e73
commit
8070746530
@@ -2,36 +2,35 @@ Unit Testing in ESP32
|
||||
=============================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively.
|
||||
ESP-IDF comes with a unit test application that is based on the Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in the ``test`` subdirectories of each component respectively.
|
||||
|
||||
Add normal test cases
|
||||
---------------------
|
||||
Normal Test Cases
|
||||
------------------
|
||||
|
||||
Unit tests are added in the ``test`` subdirectory of the respective component.
|
||||
Tests are added in C files, a single C file can include multiple test cases.
|
||||
Unit tests are located in the ``test`` subdirectory of a component.
|
||||
Tests are written in C, and a single C source file can contain multiple test cases.
|
||||
Test files start with the word "test".
|
||||
|
||||
The test file should include unity.h and the header for the C module to be tested.
|
||||
Each test file should include the ``unity.h`` header and the header for the C module to be tested.
|
||||
|
||||
Tests are added in a function in the C file as follows::
|
||||
Tests are added in a function in the C file as follows:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
TEST_CASE("test name", "[module name]"
|
||||
{
|
||||
// Add test here
|
||||
}
|
||||
|
||||
First argument is a descriptive name for the test, second argument is an identifier in square brackets.
|
||||
The first argument is a descriptive name for the test, the second argument is an identifier in square brackets.
|
||||
Identifiers are used to group related test, or tests with specific properties.
|
||||
|
||||
There is no need to add a main function with ``UNITY_BEGIN()`` and ``UNITY_END()`` in each test case.
|
||||
``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``UNITY_END()``.
|
||||
.. note::
|
||||
There is no need to add a main function with ``UNITY_BEGIN()`` and ``UNITY_END()`` in each test case. ``unity_platform.c`` will run ``UNITY_BEGIN()`` autonomously, and run the test cases, then call ``UNITY_END()``.
|
||||
|
||||
The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt <component-directories>`, since they are themselves,
|
||||
components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components
|
||||
:ref:`should list their sources manually <cmake-file-globbing>`; for component tests however, this requirement is relaxed and the
|
||||
use of ``SRC_DIRS`` argument to ``idf_component_register`` is advised.
|
||||
The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt <component-directories>`, since they are themselves, components. ESP-IDF uses the ``unity`` test framework and should be specified as a requirement for the component. Normally, components :ref:`should list their sources manually <cmake-file-globbing>`; for component tests however, this requirement is relaxed and the use of the ``SRC_DIRS`` argument in ``idf_component_register`` is advised.
|
||||
|
||||
Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as follows:
|
||||
Overall, the minimal ``test`` subdirectory ``CMakeLists.txt`` file should contain the following:
|
||||
|
||||
.. code:: cmake
|
||||
|
||||
@@ -42,13 +41,15 @@ Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as
|
||||
See http://www.throwtheswitch.org/unity for more information about writing tests in Unity.
|
||||
|
||||
|
||||
Add multiple devices test cases
|
||||
-------------------------------
|
||||
Multi-device Test Cases
|
||||
-------------------------
|
||||
|
||||
The normal test cases will be executed on one DUT (Device Under Test). Components need to communicate with each other (like GPIO, SPI ...) can't be tested with normal test cases.
|
||||
Multiple devices test cases support writing and running test with multiple DUTs.
|
||||
The normal test cases will be executed on one DUT (Device Under Test). However, components that require some form of communication (e.g., GPIO, SPI) require another device to communicate with, thus cannot be tested normal test cases.
|
||||
Multi-device test cases involve writing multiple test functions, and running them on multiple DUTs.
|
||||
|
||||
Here's an example of multiple devices test case::
|
||||
The following is an example of a multi-device test case:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void gpio_master_test()
|
||||
{
|
||||
@@ -75,12 +76,12 @@ Here's an example of multiple devices test case::
|
||||
TEST_CASE_MULTIPLE_DEVICES("gpio multiple devices test example", "[driver]", gpio_master_test, gpio_slave_test);
|
||||
|
||||
|
||||
The macro ``TEST_CASE_MULTIPLE_DEVICES`` is used to declare multiple devices test cases.
|
||||
First argument is test case name, second argument is test case description.
|
||||
From the third argument, upto 5 test functions can be defined, each function will be the entry point of tests running on each DUT.
|
||||
The macro ``TEST_CASE_MULTIPLE_DEVICES`` is used to declare a multi-device test case.
|
||||
The first argument is test case name, the second argument is test case description.
|
||||
From the third argument, up to 5 test functions can be defined, each function will be the entry point of tests running on each DUT.
|
||||
|
||||
Running test cases from different DUTs could require synchronizing between DUTs. We provide ``unity_wait_for_signal`` and ``unity_send_signal`` to support synchronizing with UART.
|
||||
As the secnario in the above example, slave should get GPIO level after master set level. DUT UART console will prompt and requires user interaction:
|
||||
As the scenario in the above example, the slave should get GPIO level after master set level. DUT UART console will prompt and user interaction is required:
|
||||
|
||||
DUT1 (master) console::
|
||||
|
||||
@@ -91,15 +92,15 @@ DUT2 (slave) console::
|
||||
|
||||
Send signal: [output high level]!
|
||||
|
||||
Once the signal is set from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level.
|
||||
Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level.
|
||||
|
||||
|
||||
Add multiple stages test cases
|
||||
-------------------------------
|
||||
Multi-stage Test Cases
|
||||
-----------------------
|
||||
|
||||
The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we want to run some specific test after certain kinds of reset.
|
||||
For example, we want to test if reset reason is correct after wakeup from deep sleep. We need to create deep sleep reset first and then check the reset reason.
|
||||
To support this, we can define multiple stages test case, to group a set of test functions together::
|
||||
The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we expect to run some specific tests after certain kinds of reset.
|
||||
For example, we expect to test if the reset reason is correct after a wakeup from deep sleep. We need to create a deep-sleep reset first and then check the reset reason.
|
||||
To support this, we can define multi-stage test cases, to group a set of test functions::
|
||||
|
||||
static void trigger_deepsleep(void)
|
||||
{
|
||||
@@ -115,22 +116,22 @@ To support this, we can define multiple stages test case, to group a set of test
|
||||
|
||||
TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[esp32]", trigger_deepsleep, check_deepsleep_reset_reason);
|
||||
|
||||
Multiple stages test cases present a group of test functions to users. It need user interactions (select case and select different stages) to run the case.
|
||||
Multi-stage test cases present a group of test functions to users. It needs user interactions (select cases and select different stages) to run the case.
|
||||
|
||||
|
||||
Building unit test app
|
||||
Building Unit Test App
|
||||
----------------------
|
||||
|
||||
Follow the setup instructions in the top-level esp-idf README.
|
||||
Make sure that IDF_PATH environment variable is set to point to the path of esp-idf top-level directory.
|
||||
Make sure that ``IDF_PATH`` environment variable is set to point to the path of esp-idf top-level directory.
|
||||
|
||||
Change into tools/unit-test-app directory to configure and build it:
|
||||
Change into ``tools/unit-test-app`` directory to configure and build it:
|
||||
|
||||
* `idf.py menuconfig` - configure unit test app.
|
||||
* ``idf.py menuconfig`` - configure unit test app.
|
||||
|
||||
* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory.
|
||||
* `idf.py -T xxx build` - build unit test app with tests for specific components.
|
||||
* `idf.py -T all -E xxxbuild` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp mbedtls build` - build all unit tests exludes ulp and mbedtls components).
|
||||
* ``idf.py -T all build`` - build unit test app with tests for each component having tests in the ``test`` subdirectory.
|
||||
* ``idf.py -T xxx build`` - build unit test app with tests for specific components.
|
||||
* ``idf.py -T all -E xxxbuild`` - build unit test app with all unit tests, except for unit tests of some components. (For instance: ``idf.py -T all -E ulp mbedtls build`` - build all unit tests exludes ``ulp`` and ``mbedtls`` components).
|
||||
|
||||
When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output.
|
||||
|
||||
@@ -138,7 +139,7 @@ You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and
|
||||
|
||||
Use menuconfig to set the serial port for flashing.
|
||||
|
||||
Running unit tests
|
||||
Running Unit Tests
|
||||
------------------
|
||||
|
||||
After flashing reset the ESP32 and it will boot the unit test app.
|
||||
@@ -171,7 +172,7 @@ When unit test app is idle, press "Enter" will make it print test menu with all
|
||||
(1) "trigger_deepsleep"
|
||||
(2) "check_deepsleep_reset_reason"
|
||||
|
||||
Normal case will print the case name and description. Master slave cases will also print the sub-menu (the registered test function names).
|
||||
The normal case will print the case name and description. Master-slave cases will also print the sub-menu (the registered test function names).
|
||||
|
||||
Test cases can be run by inputting one of the following:
|
||||
|
||||
@@ -183,25 +184,26 @@ Test cases can be run by inputting one of the following:
|
||||
|
||||
- An asterisk to run all test cases
|
||||
|
||||
``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages test case.
|
||||
``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages of test case.
|
||||
These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros.
|
||||
|
||||
After you select a multiple devices test case, it will print sub menu::
|
||||
After you select a multi-device test case, it will print sub-menu::
|
||||
|
||||
Running gpio master/slave test example...
|
||||
gpio master/slave test example
|
||||
(1) "gpio_master_test"
|
||||
(2) "gpio_slave_test"
|
||||
|
||||
You need to input number to select the test running on the DUT.
|
||||
You need to input a number to select the test running on the DUT.
|
||||
|
||||
Similar to multiple devices test cases, multiple stages test cases will also print sub menu::
|
||||
Similar to multi-device test cases, multi-stage test cases will also print sub-menu::
|
||||
|
||||
Running reset reason check for deepsleep...
|
||||
reset reason check for deepsleep
|
||||
(1) "trigger_deepsleep"
|
||||
(2) "check_deepsleep_reset_reason"
|
||||
|
||||
|
||||
First time you execute this case, input ``1`` to run first stage (trigger deepsleep).
|
||||
After DUT is rebooted and able to run test cases, select this case again and input ``2`` to run the second stage.
|
||||
The case only passes if the last stage passes and all previous stages trigger reset.
|
||||
@@ -238,4 +240,5 @@ of time spent on waiting for code/data in case of a cache miss, then subtract th
|
||||
|
||||
|
||||
One limitation of the cache compensated timer is that the task that benchmarked functions should be pinned to a core. This is due to each core having its own event counters that are independent of each other. For example, if ``ccomp_timer_start`` gets called on one core, put to sleep by the scheduler, wakes up, and gets rescheduled on the other core, then the corresponding ``ccomp_timer_stop`` will be invalid.
|
||||
invalid.
|
||||
invalid.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user