You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When you are developing an application using ESP-IDF and you are considering adding unit testing for your components functions, this extension can help to discover and execute tests on your device based on Unity as described in `Unit Testing in ESP32 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/unit-tests.html>`_ documentation.
6
+
:link_to_translation:`zh_CN:[中文]`
7
7
8
-
The extension explores tests in your current project workspace folders that follow the convension in the former documentation, this is, all tests files that follow the glob pattern specified in the **idf.unitTestFilePattern** configuration setting (default: ``**/test/test_*.c``) in your current workspace folders. The tests cases are parsed with the ``TEST_CASE\\(\"(.*)\",\\s*\"(.*)\"\\)`` regular expression matching the following test file format:
8
+
When developing an application using ESP-IDF and considering unit testing for your component functions, this extension helps discover and execute tests on your device based on Unity, as described in `Unit Testing in ESP32 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/unit-tests.html>`_.
9
+
10
+
The extension scans the workspace folders in your current project for test files that follow the convention described in the previous documentation. Specifically, it looks for files that match the glob pattern defined by the ``idf.unitTestFilePattern`` configuration setting (default: ``/test/test_*.c``). Within these files, the extension identifies test cases using the regular expression ``TEST_CASE\("(.*)",\s*"(.*)"\)``, which matches the following test file format:
9
11
10
12
.. code-block:: C
11
13
12
-
TEST_CASE("test name", "[module name]")
13
-
{
14
-
// Add test here
15
-
}
14
+
TEST_CASE("test name", "[module name]")
15
+
{
16
+
// Add test here
17
+
}
16
18
17
19
18
-
Configure the ESP-IDF Project to enable unit tests in the extension
Let's say you have a ESP-IDF project with the following structure:
23
+
Consider an ESP-IDF project with the following structure:
22
24
23
25
.. code-block::
24
26
@@ -33,64 +35,70 @@ Let's say you have a ESP-IDF project with the following structure:
33
35
* mean.c - Component source file
34
36
35
37
36
-
Inside the ``testable`` component, unit tests are added into ``test`` directory. ``test`` directorycontains source files of the tests and the component makefile (component.mk / CMakeLists.txt).
38
+
Inside the ``testable`` component, unit tests are added to the ``test`` directory, which contains the test source files and the component makefile (``component.mk``/``CMakeLists.txt``).
37
39
38
-
If you want to add tests for a ``testable`` component, just need to define a ``test`` subdirectory and add ``test_name.c`` files with the different test cases to run.
40
+
To add tests for a ``testable`` component, define a ``test`` subdirectory and add ``test_name.c`` files with different test cases to run.
39
41
40
-
This is the structure from the `ESP-IDF unit_test example <https://github.com/espressif/esp-idf/tree/master/examples/system/unit_test>`_ which can serve as reference.
42
+
This structure is from the `ESP-IDF unit_test example <https://github.com/espressif/esp-idf/tree/master/examples/system/unit_test>`_, which can serve as a reference.
41
43
42
44
.. note::
43
-
You can customize the test file discovery pattern by modifying the **idf.unitTestFilePattern** setting in your VS Code settings. This allows you to use different naming conventions or directory structures for your test files.
44
45
45
-
PyTest Embedded Services Configuration
46
+
You can customize the test file discovery pattern by modifying the ``idf.unitTestFilePattern`` setting in your VS Code settings. This allows you to use different naming conventions or directory structures for your test files.
47
+
48
+
pytest Embedded Services Configuration
46
49
--------------------------------------
47
50
48
-
The extension uses `pytest-embedded <https://docs.espressif.com/projects/pytest-embedded/en/latest/index.html>`_ to run tests on ESP-IDF devices. The **idf.pyTestEmbeddedServices** configuration setting allows you to specify which embedded services to use when running pytest commands.
51
+
The extension uses `pytest-embedded <https://docs.espressif.com/projects/pytest-embedded/en/latest/index.html>`_ to run tests on ESP-IDF devices. The ``idf.pyTestEmbeddedServices`` configuration setting allows you to specify which embedded services to use when running pytest commands.
49
52
50
53
By default, the extension uses ``["esp", "idf"]`` as the embedded services. These services provide the following functionality:
51
54
52
-
* **esp**: Enables Espressif-specific functionality including automatic target detection and port confirmation using `esptool`
53
-
* **idf**: Provides ESP-IDF project support including automatic flashing of built binaries and parsing of binary information
55
+
* **esp**: Enables Espressif-specific functionality, including automatic target detection and port confirmation using ``esptool``.
56
+
* **idf**: Provides ESP-IDF project support, including automatic flashing of built binaries and parsing of binary information.
54
57
55
-
You can customize the embedded services by modifying the **idf.pyTestEmbeddedServices** setting in your VS Code settings. For example, you might want to add additional services like:
58
+
You can customize the embedded services by modifying the ``idf.pyTestEmbeddedServices`` setting in your VS Code settings. For example, you might want to add following additional services:
56
59
57
-
* **serial**: For basic serial port communication
58
-
* **jtag**: For OpenOCD/GDB utilities
59
-
* **qemu**: For running tests on QEMU instead of real hardware
60
-
* **wokwi**: For running tests on Wokwi simulation platform
60
+
* **serial**: For basic serial port communication.
61
+
* **jtag**: For OpenOCD/GDB utilities.
62
+
* **qemu**: For running tests on QEMU instead of real hardware.
63
+
* **wokwi**: For running tests on the Wokwi simulation platform.
61
64
62
65
For a complete list of available services and their capabilities, refer to the `pytest-embedded Services Documentation <https://docs.espressif.com/projects/pytest-embedded/en/latest/concepts/services.html>`_.
63
66
64
67
.. note::
65
-
The embedded services you choose will affect the pytest command that gets executed. Make sure the services you specify are compatible with your testing environment and requirements.
68
+
69
+
The embedded services you choose will affect the pytest command that gets executed. Make sure the services you specify are compatible with your testing environment and requirements.
66
70
67
-
Running the tests
68
-
--------------------------------------------
71
+
Running the Tests
72
+
-----------------
69
73
70
-
When you click on the Testing Tab in the `Visual Studio Code Activity bar <https://code.visualstudio.com/docs/getstarted/userinterface>`_, the extension will try to find all test files and test cases and save the list of test components to add later in step 3.
74
+
When you click the ``Testing`` Tab in the `Visual Studio Code Activity bar <https://code.visualstudio.com/docs/getstarted/userinterface>`_, the extension will try to find all test files and test cases and save the list of test components to add later in step 3.
71
75
72
76
.. note::
73
-
User needs to install ESP-IDF PyTest python requirements by selecting menu **View** > **Command Palette** and type **ESP-IDF Unit Test: Install ESP-IDF PyTest requirements**. Select the command and see the pytest package installation output.
74
77
75
-
When it press the run button on a test, it will configure the current project before the tests as follows:
78
+
User needs to install ESP-IDF pytest Python requirements by selecting menu ``View`` > ``Command Palette`` and typing ``Unit Test: Install ESP-IDF pytest requirements``. Select the command and see the pytest package installation output.
76
79
77
-
1. Check that PyTest requirements from ESP-IDF are satisfied.
80
+
When you press the ``run`` button on a test, it will configure the current project before the tests as follows:
78
81
79
-
.. note::
80
-
Unit tests in this extension requires `ESP-IDF PyTest requirements <https://github.com/espressif/esp-idf/blob/master/tools/requirements/requirements.pytest.txt>`_ to be installed in your Python virtual environment.
82
+
1. Check that pytest requirements from ESP-IDF are satisfied.
81
83
82
-
2. Install ESP-IDF PyTest requirements if they are not found in the python current virtual environment specified in **idf.toolsPath** configuration setting in settings.json.
84
+
.. note::
83
85
84
-
3. Copy the unity-app from the extension template and add the test components to the main CMakeLists.txt ``TEST_COMPONENTS`` cmake variable. The extension unity-app is a basic ESP-IDF application with a unity menu that will be built and flashed on the current **idf.port** serial device with all test cases that were found during exploration step.
86
+
Unit tests in this extension requires `ESP-IDF pytest requirements <https://github.com/espressif/esp-idf/blob/master/tools/requirements/requirements.pytest.txt>`_ to be installed in your Python virtual environment.
85
87
86
-
.. note::
87
-
You can also create, build and flash the unity test application using the **ESP-IDF Unit Test: Install ESP-IDF PyTest requirements** extension command, which will copy build and flash to your device the generated unit testing application.
88
+
2. Install ESP-IDF pytest requirements if they are not found in the python current virtual environment specified in ``idf.toolsPath`` configuration setting in ``settings.json``.
88
89
89
-
4. Runs `pytest-embedded <https://docs.espressif.com/projects/pytest-embedded/en/latest/index.html>`_ a plugin that extends PyTest to run on esp-idf devices and output the results as XML file in the unity-app directory. This is executed as an extension task and the output shown in the terminal (similar to Build and Flash tasks). The pytest command uses the embedded services specified in the **idf.pyTestEmbeddedServices** configuration setting (default: ``["esp", "idf"]``).
90
+
3. Copy the ``unity-app`` from the extension template, and add the required test components to the ``TEST_COMPONENTS`` CMake variable in the main ``CMakeLists.txt``. The ``unity-app`` provided by the extension is a simple ESP-IDF application that includes a Unity menu. It will be built and flashed to the serial device defined by ``idf.port``, together with all the test cases discovered during the exploration step.
90
91
91
-
.. note::
92
-
You can customize the embedded services used by pytest by modifying the **idf.pyTestEmbeddedServices** setting in your VS Code settings. This allows you to specify different services or add additional ones as needed for your testing environment.
92
+
.. note::
93
+
94
+
You can also create, build and flash the unity test application using the ``Unit Test: Install ESP-IDF pytest requirements`` extension command, which will copy, build, and flash the generated unit testing application to your device.
95
+
96
+
4. Run `pytest-embedded <https://docs.espressif.com/projects/pytest-embedded/en/latest/index.html>`_, a plugin that extends pytest to run on ESP-IDF devices and output the results as an XML file in the ``unity-app`` directory. This is executed as an extension task, and the output is shown in the terminal (similar to build and flash tasks). The pytest command uses the embedded services specified in the ``idf.pyTestEmbeddedServices`` configuration setting (default: ``["esp", "idf"]``).
97
+
98
+
.. note::
99
+
100
+
You can customize the embedded services used by pytest by modifying the ``idf.pyTestEmbeddedServices`` setting in your VS Code settings. This allows you to specify different services or add additional ones as needed for your testing environment.
93
101
94
-
5. The XML results file is parsed and test results are updated in the Testing tab with test duration.
102
+
5. The XML results file is parsed, and test results are updated in the ``Testing`` tab with test duration.
95
103
96
-
6. You can refresh the tests and build the unity-app again with the ``Refresh Tests`` button from the Testing tab.
104
+
6. You can refresh the tests and build the ``unity-app`` again with the ``Refresh Tests`` button from the ``Testing`` tab.
0 commit comments