From 0f019b79a24842b5448e73188ed05b3818bad38f Mon Sep 17 00:00:00 2001 From: Shen Mengjing Date: Wed, 17 Sep 2025 12:14:13 +0800 Subject: [PATCH] Provide CN translation for unit-testing.rst (resubmit) docs: Fix a build error --- docs_espressif/en/additionalfeatures.rst | 2 +- .../en/additionalfeatures/unit-testing.rst | 92 ++++++++++--------- docs_espressif/zh_CN/additionalfeatures.rst | 2 +- .../zh_CN/additionalfeatures/unit-testing.rst | 92 ++++++++++--------- package.nls.json | 2 +- package.nls.zh-CN.json | 2 +- 6 files changed, 104 insertions(+), 88 deletions(-) diff --git a/docs_espressif/en/additionalfeatures.rst b/docs_espressif/en/additionalfeatures.rst index 6a90f34ff..866c8b439 100644 --- a/docs_espressif/en/additionalfeatures.rst +++ b/docs_espressif/en/additionalfeatures.rst @@ -26,7 +26,7 @@ Additional IDE Features Project Configuration Editor QEMU ESP RainMaker - Unit Testing + Unit Testing with Unity Working with Multiple Projects Using WSL in Windows Web Extension diff --git a/docs_espressif/en/additionalfeatures/unit-testing.rst b/docs_espressif/en/additionalfeatures/unit-testing.rst index 1641043a4..17a3366b8 100644 --- a/docs_espressif/en/additionalfeatures/unit-testing.rst +++ b/docs_espressif/en/additionalfeatures/unit-testing.rst @@ -1,24 +1,26 @@ .. _unit testing: -ESP-IDF Unit testing with Unity -=================================== +Unit Testing with Unity +======================= -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 `_ documentation. +:link_to_translation:`zh_CN:[中文]` -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: +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 `_. + +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: .. code-block:: C - TEST_CASE("test name", "[module name]") - { - // Add test here - } + TEST_CASE("test name", "[module name]") + { + // Add test here + } -Configure the ESP-IDF Project to enable unit tests in the extension -------------------------------------------------------------------------- +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: +Consider an ESP-IDF project with the following structure: .. code-block:: @@ -33,64 +35,70 @@ Let's say you have a ESP-IDF project with the following structure: * mean.c - Component source file -Inside the ``testable`` component, unit tests are added into ``test`` directory. ``test`` directory contains source files of the tests and the component makefile (component.mk / CMakeLists.txt). +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``). -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. +To add tests for a ``testable`` component, define a ``test`` subdirectory and add ``test_name.c`` files with different test cases to run. -This is the structure from the `ESP-IDF unit_test example `_ which can serve as reference. +This structure is from the `ESP-IDF unit_test example `_, which can serve as a reference. .. 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 + 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 `_ 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. +The extension uses `pytest-embedded `_ 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 +* **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: +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: -* **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 +* **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 the Wokwi simulation platform. For a complete list of available services and their capabilities, refer to the `pytest-embedded Services Documentation `_. .. 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. + + 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 --------------------------------------------- +Running the Tests +----------------- -When you click on the Testing Tab in the `Visual Studio Code Activity bar `_, 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. +When you click the ``Testing`` Tab in the `Visual Studio Code Activity bar `_, 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: + 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. -1. Check that PyTest requirements from ESP-IDF are satisfied. +When you press the ``run`` button on a test, it will configure the current project before the tests as follows: -.. note:: - Unit tests in this extension requires `ESP-IDF PyTest requirements `_ to be installed in your Python virtual environment. +1. Check that pytest requirements from ESP-IDF are satisfied. -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. + .. note:: -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. + Unit tests in this extension requires `ESP-IDF pytest requirements `_ to be installed in your Python virtual environment. -.. 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. +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``. -4. Runs `pytest-embedded `_ 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"]``). +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. -.. 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. + .. note:: + + 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. + +4. Run `pytest-embedded `_, 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"]``). + + .. 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. -5. The XML results file is parsed and test results are updated in the Testing tab with test duration. +5. The XML results file is parsed, and test results are updated in the ``Testing`` tab with test duration. -6. You can refresh the tests and build the unity-app again with the ``Refresh Tests`` button from the Testing tab. +6. You can refresh the tests and build the ``unity-app`` again with the ``Refresh Tests`` button from the ``Testing`` tab. diff --git a/docs_espressif/zh_CN/additionalfeatures.rst b/docs_espressif/zh_CN/additionalfeatures.rst index be84c0463..15439eaca 100644 --- a/docs_espressif/zh_CN/additionalfeatures.rst +++ b/docs_espressif/zh_CN/additionalfeatures.rst @@ -25,7 +25,7 @@ 项目配置编辑器 QEMU 模拟器 ESP RainMaker - 单元测试 + 使用 Unity 框架进行单元测试 处理多个项目 在 Windows 系统中使用 WSL Web Extension diff --git a/docs_espressif/zh_CN/additionalfeatures/unit-testing.rst b/docs_espressif/zh_CN/additionalfeatures/unit-testing.rst index 71056b5b0..a896b90f3 100644 --- a/docs_espressif/zh_CN/additionalfeatures/unit-testing.rst +++ b/docs_espressif/zh_CN/additionalfeatures/unit-testing.rst @@ -1,24 +1,26 @@ .. _unit testing: -使用 Unity 进行 ESP-IDF 单元测试 -=================================== +使用 Unity 框架进行单元测试 +============================= -当您使用 ESP-IDF 开发应用程序并考虑为组件函数添加单元测试时，此扩展可以帮助基于 Unity 在您的设备上发现和执行测试，如 `ESP32 单元测试 `_ 文档中所述。 +:link_to_translation:`en:[English]` -扩展会在当前项目工作区文件夹中探索遵循前述文档约定的测试，即所有遵循 **idf.unitTestFilePattern** 配置设置中指定的 glob 模式（默认：``**/test/test_*.c``）的测试文件。测试用例通过 ``TEST_CASE\\(\"(.*)\",\\s*\"(.*)\"\\)`` 正则表达式进行解析，匹配以下测试文件格式： +使用 ESP-IDF 开发应用程序并考虑为组件函数添加单元测试时，你可以使用此扩展，基于 Unity 框架在设备上发现和执行测试，详情请参考 `ESP32 中的单元测试 `_。 + +扩展会扫描当前项目的工作区文件夹，寻找所有符合规范的测试文件，即所有符合 ``idf.unitTestFilePattern`` 配置项中指定通配符模式的测试文件（默认是 ``**/test/test_*.c``）。找到测试文件后，扩展会通过正则表达式 ``TEST_CASE\\(\"(.*)\",\\s*\"(.*)\"\\)`` 解析文件中的测试用例。具体而言，这些正则表达式会匹配如下测试文件格式： .. code-block:: C - TEST_CASE("test name", "[module name]") - { - // Add test here - } + TEST_CASE("test name", "[module name]") + { + // 在此处添加测试 + } 配置 ESP-IDF 项目以在扩展中启用单元测试 -------------------------------------------------------------------------- +---------------------------------------- -假设您有一个具有以下结构的 ESP-IDF 项目： +假设有一个 ESP-IDF 项目，结构如下： .. code-block:: @@ -33,64 +35,70 @@ * mean.c - 组件源文件 -在 ``testable`` 组件内，单元测试添加到 ``test`` 目录中。``test`` 目录包含测试的源文件和组件 makefile（component.mk / CMakeLists.txt）。 +在 ``testable`` 组件内，单元测试添加到 ``test`` 目录中，其中包含测试的源文件和组件 makefile (``component.mk``/``CMakeLists.txt``)。 -如果您想为 ``testable`` 组件添加测试，只需定义一个 ``test`` 子目录并添加包含不同测试用例的 ``test_name.c`` 文件即可运行。 +如果想要为 ``testable`` 组件添加测试，只需定义一个 ``test`` 子目录并添加包含不同测试用例的 ``test_name.c`` 文件即可运行。 -这是来自 `ESP-IDF unit_test 示例 `_ 的结构，可以作为参考。 +此结构来自 `ESP-IDF unit_test 示例 `_，可以作为参考。 .. note:: - 您可以通过修改 VS Code 设置中的 **idf.unitTestFilePattern** 设置来自定义测试文件发现模式。这允许您为测试文件使用不同的命名约定或目录结构。 -PyTest 嵌入式服务配置 --------------------------------------- + 你可以通过修改 VS Code 设置中的 ``idf.unitTestFilePattern`` 配置项来自定义测试文件发现模式，为测试文件使用不同的命名方式或目录结构。 + +pytest 嵌入式服务配置 +--------------------- -扩展使用 `pytest-embedded `_ 在 ESP-IDF 设备上运行测试。**idf.pyTestEmbeddedServices** 配置设置允许您指定运行 pytest 命令时要使用的嵌入式服务。 +扩展使用 `pytest-embedded `_ 在 ESP-IDF 设备上运行测试。可以通过 ``idf.pyTestEmbeddedServices`` 配置项指定运行 pytest 命令时使用的嵌入式服务。 -默认情况下，扩展使用 ``["esp", "idf"]`` 作为嵌入式服务。这些服务提供以下功能： +默认情况下，扩展使用 ``["esp", "idf"]`` 作为嵌入式服务。服务提供以下功能： -* **esp**：启用乐鑫特定功能，包括使用 `esptool` 进行自动目标检测和端口确认 -* **idf**：提供 ESP-IDF 项目支持，包括自动烧录构建的二进制文件和解析二进制信息 +* **esp**：启用乐鑫特有功能，包括使用 ``esptool`` 进行目标自动检测和端口确认。 +* **idf**：提供 ESP-IDF 项目支持，包括自动烧录构建的二进制文件和解析二进制信息。 -您可以通过修改 VS Code 设置中的 **idf.pyTestEmbeddedServices** 设置来自定义嵌入式服务。例如，您可能想要添加其他服务，如： +通过修改 VS Code 设置中的 ``idf.pyTestEmbeddedServices`` 配置项，可以自定义嵌入式服务。例如，你可以添加以下服务： -* **serial**：用于基本串口通信 -* **jtag**：用于 OpenOCD/GDB 工具 -* **qemu**：用于在 QEMU 而不是真实硬件上运行测试 -* **wokwi**：用于在 Wokwi 仿真平台上运行测试 +* **serial**：用于基本串口通信。 +* **jtag**：用于 OpenOCD/GDB 工具。 +* **qemu**：用于在 QEMU 而不是真实硬件上运行测试。 +* **wokwi**：用于在 Wokwi 仿真平台上运行测试。 有关可用服务及其功能的完整列表，请参阅 `pytest-embedded 服务文档 `_。 .. note:: - 您选择的嵌入式服务将影响执行的 pytest 命令。确保您指定的服务与您的测试环境和要求兼容。 + + 你选择的嵌入式服务将影响执行的 pytest 命令。请确保你指定的服务与你的测试环境和要求兼容。 运行测试 --------------------------------------------- +-------- -当您点击 `Visual Studio Code 活动栏 `_ 中的测试选项卡时，扩展将尝试查找所有测试文件和测试用例，并保存测试组件列表以便在步骤 3 中添加。 +点击 `Visual Studio Code 活动栏 `_ 中的 ``Testing`` 选项卡时，扩展将尝试查找所有测试文件和测试用例，并保存测试组件列表以便在步骤 3 中添加。 .. note:: - 用户需要通过选择菜单 **查看** > **命令面板** 并输入 **ESP-IDF 单元测试：安装 ESP-IDF PyTest 要求** 来安装 ESP-IDF PyTest python 要求。选择命令并查看 pytest 包安装输出。 -当按下测试上的运行按钮时，它将在测试前按如下方式配置当前项目： + 用户需要安装 ESP-IDF pytest 的 Python 的依赖。请前往菜单栏选择 ``查看`` > ``命令面板``，输入 ``单元测试：安装 ESP-IDF pytest 依赖项``，选择该命令后，即可查看 pytest 包的安装输出。 -1. 检查 ESP-IDF 的 PyTest 要求是否满足。 +按下测试中的 ``run`` 按钮时，系统将在测试前按如下方式配置当前项目： -.. note:: - 此扩展中的单元测试需要在您的 Python 虚拟环境中安装 `ESP-IDF PyTest 要求 `_。 +1. 检查 ESP-IDF 的 pytest 依赖项是否满足。 -2. 如果在 settings.json 中 **idf.toolsPath** 配置设置指定的 python 当前虚拟环境中未找到，则安装 ESP-IDF PyTest 要求。 + .. note:: -3. 从扩展模板复制 unity-app 并将测试组件添加到主 CMakeLists.txt 的 ``TEST_COMPONENTS`` cmake 变量中。扩展 unity-app 是一个基本的 ESP-IDF 应用程序，带有 unity 菜单，将在当前 **idf.port** 串行设备上构建和烧录，包含在探索步骤中找到的所有测试用例。 + 若想在此扩展中进行单元测试，需要先在你的 Python 虚拟环境中安装 `ESP-IDF pytest 依赖项 `_。 -.. note:: - 您也可以使用 **ESP-IDF 单元测试：安装 ESP-IDF PyTest 要求** 扩展命令创建、构建和烧录 unity 测试应用程序，该命令将复制构建并烧录生成的单元测试应用程序到您的设备。 +2. 如果在 ``settings.json`` 文件中 ``idf.toolsPath`` 配置项所指定的 Python 虚拟环境中未找到 ESP-IDF 所需的 pytest 依赖，则系统会自动安装这些依赖。 -4. 运行 `pytest-embedded `_，这是一个扩展 PyTest 以在 esp-idf 设备上运行的插件，并在 unity-app 目录中以 XML 文件形式输出结果。这作为扩展任务执行，输出显示在终端中（类似于构建和烧录任务）。pytest 命令使用 **idf.pyTestEmbeddedServices** 配置设置中指定的嵌入式服务（默认：``["esp", "idf"]``）。 +3. 从扩展模板中复制 ``unity-app``，并将所需的测试组件添加到主 ``CMakeLists.txt`` 文件的 ``TEST_COMPONENTS`` CMake 变量中。扩展提供的 ``unity-app`` 是一个包含 Unity 菜单的简单 ESP-IDF 应用程序，该程序会和探索步骤中发现的测试用例一起被构建并烧录到 ``idf.port`` 指定的串口设备上。 -.. note:: - 您可以通过修改 VS Code 设置中的 **idf.pyTestEmbeddedServices** 设置来自定义 pytest 使用的嵌入式服务。这允许您指定不同的服务或根据需要为测试环境添加其他服务。 + .. note:: + + 你也可以使用 ``单元测试：安装 ESP-IDF pytest 依赖项`` 扩展命令，来创建、构建和烧录单元测试应用程序。该命令将把生成的单元测试应用程序复制、构建并烧录到你的设备上。 + +4. 扩展会运行 `pytest-embedded `_ 插件，让 pytest 在 ESP-IDF 设备上执行测试，并把结果保存为 XML 文件放到 ``unity-app`` 目录。这个过程作为扩展任务执行，结果会显示在终端里（类似于构建和烧录任务）。pytest 的运行还依赖 ``idf.pyTestEmbeddedServices`` 配置项指定的服务（默认是 ``["esp", "idf"]``）。 + + .. note:: + + 你可以通过修改 VS Code 设置中的 ``idf.pyTestEmbeddedServices`` 配置项来自定义 pytest 使用的嵌入式服务，从而指定不同的服务或根据需要为测试环境添加其他服务。 -5. 解析 XML 结果文件，并在测试选项卡中更新测试结果，显示测试持续时间。 +5. 解析 XML 结果文件，并在 ``Testing`` 选项卡中更新测试结果，显示测试持续时间。 -6. 您可以使用测试选项卡中的 ``刷新测试`` 按钮刷新测试并再次构建 unity-app。 +6. 你可以使用 ``Testing`` 选项卡中的 ``Refresh Tests`` 按钮刷新测试并再次构建 ``unity-app``。 diff --git a/package.nls.json b/package.nls.json index 9cb08f006..e0314fc9b 100644 --- a/package.nls.json +++ b/package.nls.json @@ -94,7 +94,7 @@ "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.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", diff --git a/package.nls.zh-CN.json b/package.nls.zh-CN.json index c7da2ed3e..931e2ceef 100644 --- a/package.nls.zh-CN.json +++ b/package.nls.zh-CN.json @@ -94,7 +94,7 @@ "espIdf.unitTest.buildFlashUnitTestApp.title": "单元测试：构建并烧录单元测试应用程序", "espIdf.unitTest.buildUnitTestApp.title": "单元测试：构建单元测试应用程序", "espIdf.unitTest.flashUnitTestApp.title": "单元测试：烧录单元测试应用程序", - "espIdf.unitTest.installPyTest.title": "单元测试：安装 ESP-IDF PyTest 依赖项", + "espIdf.unitTest.installPyTest.title": "单元测试：安装 ESP-IDF pytest 依赖项", "espIdf.viewAsHex.title": "以十六进制查看", "espIdf.hexView.copyValue.title": "复制值到剪贴板", "espIdf.hexView.deleteElement.title": "从列表中删除十六进制值",