Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 5 additions & 40 deletions docs_espressif/en/additionalfeatures/unit-testing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,55 +42,20 @@ This is the structure from the `ESP-IDF unit_test example <https://github.com/es
.. note::
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.

PyTest Embedded Services Configuration
--------------------------------------

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.

By default, the extension uses ``["esp", "idf"]`` as the embedded services. These services provide the following functionality:

* **esp**: Enables Espressif-specific functionality including automatic target detection and port confirmation using `esptool`
* **idf**: Provides ESP-IDF project support including automatic flashing of built binaries and parsing of binary information

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:

* **serial**: For basic serial port communication
* **jtag**: For OpenOCD/GDB utilities
* **qemu**: For running tests on QEMU instead of real hardware
* **wokwi**: For running tests on Wokwi simulation platform

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

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

Running the tests
--------------------------------------------

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.

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

When it press the run button on a test, it will configure the current project before the tests as follows:

1. Check that PyTest requirements from ESP-IDF are satisfied.

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

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.

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.

.. note::
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.
1. 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.

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"]``).
2. Build and flash the unity-app to the device.

.. note::
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.
You can also create, build and flash the unity test application using the **ESP-IDF Unit Test: Build Unit Test App** and **ESP-IDF Unit Test: Flash Unit Test App** extension commands respectively, which will copy build and flash to your device the generated unit testing application.

5. The XML results file is parsed and test results are updated in the Testing tab with test duration.
3. Capture the serial output from the device and parse the test results to show them in the ``Testing`` tab. The output from serial port is also shown in the ``ESP-IDF`` output channel.

6. You can refresh the tests and build the unity-app again with the ``Refresh Tests`` button from the Testing tab.
4. You can refresh the tests and build the unity-app again with the ``Refresh Tests`` button from the ``Testing`` tab.
9 changes: 3 additions & 6 deletions docs_espressif/en/settings.rst
Original file line number Diff line number Diff line change
Expand Up @@ -170,10 +170,10 @@ These settings are used to configure the code coverage colors.
- Background color for uncovered lines in dark theme for gcov coverage


PyTest Specific Settings
------------------------
Unit test Specific Settings
-----------------------------

These settings are used to configure unit testing with PyTest.
These settings are used to configure unit testing.

.. list-table::
:widths: 25 75
Expand All @@ -183,13 +183,10 @@ These settings are used to configure unit testing with PyTest.
- Description
* - **idf.unitTestFilePattern**
- Glob pattern for unit test files to discover (default: ``**/test/test_*.c``)
* - **idf.pyTestEmbeddedServices**
- List of embedded services for pytest execution (default: ``["esp", "idf"]``)

This is how the extension uses them:

1. **idf.unitTestFilePattern** is used by the extension to discover unit test files in your project. The default pattern :code:`**/test/test_*.c` looks for C files names starting with "test" in any "test" directory.
2. **idf.pyTestEmbeddedServices** specifies the embedded services to use when running pytest commands. These services are passed to the pytest command as the :code:`--embedded-services` parameter.


Extension Behaviour Settings
Expand Down
45 changes: 5 additions & 40 deletions docs_espressif/zh_CN/additionalfeatures/unit-testing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,55 +42,20 @@
.. note::
您可以通过修改 VS Code 设置中的 **idf.unitTestFilePattern** 设置来自定义测试文件发现模式。这允许您为测试文件使用不同的命名约定或目录结构。

PyTest 嵌入式服务配置
--------------------------------------

扩展使用 `pytest-embedded <https://docs.espressif.com/projects/pytest-embedded/en/latest/index.html>`_ 在 ESP-IDF 设备上运行测试。**idf.pyTestEmbeddedServices** 配置设置允许您指定运行 pytest 命令时要使用的嵌入式服务。

默认情况下,扩展使用 ``["esp", "idf"]`` 作为嵌入式服务。这些服务提供以下功能:

* **esp**:启用乐鑫特定功能,包括使用 `esptool` 进行自动目标检测和端口确认
* **idf**:提供 ESP-IDF 项目支持,包括自动烧录构建的二进制文件和解析二进制信息

您可以通过修改 VS Code 设置中的 **idf.pyTestEmbeddedServices** 设置来自定义嵌入式服务。例如,您可能想要添加其他服务,如:

* **serial**:用于基本串口通信
* **jtag**:用于 OpenOCD/GDB 工具
* **qemu**:用于在 QEMU 而不是真实硬件上运行测试
* **wokwi**:用于在 Wokwi 仿真平台上运行测试

有关可用服务及其功能的完整列表,请参阅 `pytest-embedded 服务文档 <https://docs.espressif.com/projects/pytest-embedded/en/latest/concepts/services.html>`_。

.. note::
您选择的嵌入式服务将影响执行的 pytest 命令。确保您指定的服务与您的测试环境和要求兼容。

运行测试
--------------------------------------------

当您点击 `Visual Studio Code 活动栏 <https://code.visualstudio.com/docs/getstarted/userinterface>`_ 中的测试选项卡时,扩展将尝试查找所有测试文件和测试用例,并保存测试组件列表以便在步骤 3 中添加。

.. note::
用户需要通过选择菜单 **查看** > **命令面板** 并输入 **ESP-IDF 单元测试:安装 ESP-IDF PyTest 要求** 来安装 ESP-IDF PyTest python 要求。选择命令并查看 pytest 包安装输出。

当按下测试上的运行按钮时,它将在测试前按如下方式配置当前项目:

1. 检查 ESP-IDF 的 PyTest 要求是否满足。

.. note::
此扩展中的单元测试需要在您的 Python 虚拟环境中安装 `ESP-IDF PyTest 要求 <https://github.com/espressif/esp-idf/blob/master/tools/requirements/requirements.pytest.txt>`_。

2. 如果在 settings.json 中 **idf.toolsPath** 配置设置指定的 python 当前虚拟环境中未找到,则安装 ESP-IDF PyTest 要求。

3. 从扩展模板复制 unity-app 并将测试组件添加到主 CMakeLists.txt 的 ``TEST_COMPONENTS`` cmake 变量中。扩展 unity-app 是一个基本的 ESP-IDF 应用程序,带有 unity 菜单,将在当前 **idf.port** 串行设备上构建和烧录,包含在探索步骤中找到的所有测试用例。

.. note::
您也可以使用 **ESP-IDF 单元测试:安装 ESP-IDF PyTest 要求** 扩展命令创建、构建和烧录 unity 测试应用程序,该命令将复制构建并烧录生成的单元测试应用程序到您的设备。
1. 从扩展模板复制 unity-app 并将测试组件添加到主 CMakeLists.txt 的 ``TEST_COMPONENTS`` cmake 变量中。扩展 unity-app 是一个基本的 ESP-IDF 应用程序,带有 unity 菜单,将在当前 **idf.port** 串行设备上构建和烧录,包含在探索步骤中找到的所有测试用例。

4. 运行 `pytest-embedded <https://docs.espressif.com/projects/pytest-embedded/en/latest/index.html>`_,这是一个扩展 PyTest 以在 esp-idf 设备上运行的插件,并在 unity-app 目录中以 XML 文件形式输出结果。这作为扩展任务执行,输出显示在终端中(类似于构建和烧录任务)。pytest 命令使用 **idf.pyTestEmbeddedServices** 配置设置中指定的嵌入式服务(默认:``["esp", "idf"]``)
2. 构建并烧录 unity-app 到设备

.. note::
您可以通过修改 VS Code 设置中的 **idf.pyTestEmbeddedServices** 设置来自定义 pytest 使用的嵌入式服务。这允许您指定不同的服务或根据需要为测试环境添加其他服务
您也可以使用 **ESP-IDF 单元测试:构建单元测试应用** 和 **ESP-IDF 单元测试:烧录单元测试应用** 扩展命令分别创建、构建和烧录 unity 测试应用程序,这些命令将复制构建并烧录生成的单元测试应用程序到您的设备

5. 解析 XML 结果文件,并在测试选项卡中更新测试结果,显示测试持续时间
3. 捕获设备的串口输出并解析测试结果以在 ``测试`` 选项卡中显示。串口输出也会显示在 ``ESP-IDF`` 输出通道中

6. 您可以使用测试选项卡中的 ``刷新测试`` 按钮刷新测试并再次构建 unity-app。
4. 您可以使用 ``测试`` 选项卡中的 ``刷新测试`` 按钮刷新测试并再次构建 unity-app。
2 changes: 0 additions & 2 deletions docs_espressif/zh_CN/commands.rst
Original file line number Diff line number Diff line change
Expand Up @@ -134,5 +134,3 @@
- 将当前项目的单元测试应用程序烧录到连接的设备上。详情请参阅 :ref:`单元测试 <unit testing>`。
* - 单元测试:构建并烧录单元测试应用程序
- 复制当前项目中的单元测试应用程序,构建当前项目并将单元测试应用程序烧录到连接的设备上。详情请参阅 :ref:`单元测试 <unit testing>`。
* - 单元测试:安装 ESP-IDF PyTest 依赖项
- 安装 ESP-IDF Pytest 依赖项,以便能够执行 ESP-IDF 单元测试。详情请参阅 :ref:`单元测试 <unit testing>`。
3 changes: 0 additions & 3 deletions docs_espressif/zh_CN/settings.rst
Original file line number Diff line number Diff line change
Expand Up @@ -171,13 +171,10 @@ PyTest 相关设置
- 描述
* - **idf.unitTestFilePattern**
- 用于发现单元测试文件的 glob 模式(默认值:``**/test/test_*.c``)
* - **idf.pyTestEmbeddedServices**
- pytest 执行的内嵌服务列表(默认值:``["esp", "idf"]``)

扩展将按照以下方式使用上述设置:

1. **idf.unitTestFilePattern** 用于扩展在项目中发现单元测试文件。默认模式 :code:`**/test/test_*.c` 会在任何 "test" 目录中查找以 "test" 开头的 C 文件。
2. **idf.pyTestEmbeddedServices** 指定运行 pytest 命令时使用的内嵌服务。这些服务会作为 :code:`--embedded-services` 参数传递给 pytest 命令。


扩展行为设置
Expand Down
17 changes: 0 additions & 17 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -1278,18 +1278,6 @@
"scope": "resource",
"default": "**/test/test_*.c"
},
"idf.pyTestEmbeddedServices": {
"type": "array",
"description": "%param.pyTestEmbeddedServices.title%",
"scope": "resource",
"default": [
"esp",
"idf"
],
"items": {
"type": "string"
}
},
"idf.serialPortDetectionTimeout": {
"type": "number",
"default": 60,
Expand Down Expand Up @@ -1772,11 +1760,6 @@
"title": "%espIdf.selectNotificationMode.title%",
"category": "ESP-IDF"
},
{
"command": "espIdf.unitTest.installPyTest",
"title": "%espIdf.unitTest.installPyTest.title%",
"category": "ESP-IDF"
},
{
"command": "espIdf.unitTest.buildFlashUnitTestApp",
"title": "%espIdf.unitTest.buildFlashUnitTestApp.title%",
Expand Down
2 changes: 0 additions & 2 deletions package.nls.es.json
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,6 @@
"espIdf.unitTest.buildFlashUnitTestApp.title": "Prueba unitaria: Construir y flashear la aplicación de prueba unitaria para pruebas",
"espIdf.unitTest.buildUnitTestApp.title": "Prueba unitaria: Construir aplicación de prueba unitaria",
"espIdf.unitTest.flashUnitTestApp.title": "Prueba unitaria: Flashear aplicación de prueba unitaria",
"espIdf.unitTest.installPyTest.title": "Prueba unitaria: Instalar requisitos de PyTest de ESP-IDF",
"espIdf.webview.nvsPartitionEditor.title": "Abrir Editor de Partición NVS",
"espIdf.welcome.title": "Bienvenido",
"espIdf.viewAsHex.title": "Ver como Hexadecimal",
Expand Down Expand Up @@ -186,7 +185,6 @@
"param.usbSerialPortFilters.productId": "Número hexadecimal del USB productID como texto.",
"param.hasWalkthroughBeenShown": "Indica si se ha mostrado el recorrido de bienvenida",
"param.unitTestFilePattern.title": "Patrón glob para descubrir archivos de prueba unitaria",
"param.pyTestEmbeddedServices.title": "Lista de servicios integrados para la ejecución de pytest",
"param.serialPortDetectionTimeout": "Tiempo de espera en segundos para la detección del puerto serie usando esptool.py",
"trace.poll_period.description": "poll_period se establecerá para el rastreo de la aplicación",
"trace.skip_size.description": "skip_size se establecerá para el rastreo de la aplicación",
Expand Down
2 changes: 0 additions & 2 deletions package.nls.json
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,6 @@
"espIdf.unitTest.buildFlashUnitTestApp.title": "Unit Test: Build and Flash Unit Test App for Testing",
"espIdf.unitTest.buildUnitTestApp.title": "Unit Test: Build Unit Test App",
"espIdf.unitTest.flashUnitTestApp.title": "Unit Test: Flash Unit Test App",
"espIdf.unitTest.installPyTest.title": "Unit Test: Install ESP-IDF PyTest Requirements",
"espIdf.viewAsHex.title": "View as Hex",
"espIdf.hexView.copyValue.title": "Copy value to clipboard",
"espIdf.hexView.deleteElement.title": "Delete hex value from list",
Expand Down Expand Up @@ -187,7 +186,6 @@
"param.usbSerialPortFilters.productId": "USB Product ID hex number as string, e.g., 0x6010",
"param.hasWalkthroughBeenShown": "Has the walkthrough been shown",
"param.unitTestFilePattern.title": "Glob pattern for unit test files to discover",
"param.pyTestEmbeddedServices.title": "List of embedded services for pytest execution",
"param.serialPortDetectionTimeout": "Timeout in seconds for serial port detection using esptool.py",
"trace.poll_period.description": "poll_period will be set for the apptrace",
"trace.skip_size.description": "skip_size will be set for the apptrace",
Expand Down
2 changes: 0 additions & 2 deletions package.nls.pt.json
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,6 @@
"espIdf.unitTest.buildFlashUnitTestApp.title": "Teste de unidade: crie e atualize o aplicativo de teste de unidade para teste",
"espIdf.unitTest.buildUnitTestApp.title": "Teste de unidade: criar aplicativo de teste de unidade",
"espIdf.unitTest.flashUnitTestApp.title": "Teste de unidade: atualizar aplicativo de teste de unidade",
"espIdf.unitTest.installPyTest.title": "Teste de unidade: instale os requisitos do ESP-IDF PyTest",
"espIdf.webview.nvsPartitionEditor.title": "Abra o Editor de Partição NVS",
"espIdf.welcome.title": "Bem-vindo",
"espIdf.viewAsHex.title": "Ver como Hexadecimal",
Expand Down Expand Up @@ -185,7 +184,6 @@
"param.usbSerialPortFilters.productId": "Número hexadecimal de USB productID como string.",
"param.hasWalkthroughBeenShown": "Mostrar o guia de introdução na inicialização da extensão",
"param.unitTestFilePattern.title": "Padrão glob para descobrir arquivos de teste unitário",
"param.pyTestEmbeddedServices.title": "Lista de serviços incorporados para execução do pytest",
"param.serialPortDetectionTimeout": "Tempo limite em segundos para detecção de porta serial usando esptool.py",
"trace.poll_period.description": "poll_period será definido para o apptrace",
"trace.skip_size.description": "skip_size será definido para o apptrace",
Expand Down
2 changes: 0 additions & 2 deletions package.nls.ru.json
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,6 @@
"espIdf.unitTest.buildFlashUnitTestApp.title": "Unit Test: Сборка и прошивка Unit Test App для тестирования",
"espIdf.unitTest.buildUnitTestApp.title": "Unit Test: Сборка Unit Test App",
"espIdf.unitTest.flashUnitTestApp.title": "Unit Test: Прошивка Unit Test App",
"espIdf.unitTest.installPyTest.title": "Unit Test: Установка требований ESP-IDF PyTest.",
"espIdf.viewAsHex.title": "Просмотреть как шестнадцатеричное",
"espIdf.hexView.copyValue.title": "Скопировать значение в буфер обмена",
"espIdf.hexView.deleteElement.title": "Удалить шестнадцатеричное значение из списка",
Expand Down Expand Up @@ -186,7 +185,6 @@
"param.usbSerialPortFilters.productId": "Шестнадцатеричное число USB Product ID в виде строки, например, 0x6010",
"param.hasWalkthroughBeenShown": "Показывать руководство по настройке ESP-IDF при первом запуске",
"param.unitTestFilePattern.title": "Шаблон glob для обнаружения файлов модульных тестов",
"param.pyTestEmbeddedServices.title": "Список встроенных сервисов для выполнения pytest",
"param.serialPortDetectionTimeout": "Тайм-аут в секундах для обнаружения последовательного порта с помощью esptool.py",
"trace.poll_period.description": "для apptrace будет установлен параметр poll_ period",
"trace.skip_size.description": "для apptrace будет установлен параметр skip_size",
Expand Down
Loading