ci: apply idf-ci 1.x

(cherry picked from commit 21d772a24da646bfb672418cf056199cad9b17e4)

docs/en/api-guides/tools/idf-tools.rst

@@ -45,6 +45,8 @@ Inside the ``IDF_TOOLS_PATH`` directory, the tools installation scripts create t
 - ``python_env`` —  not related to the tools; virtual Python environments are installed in the sub-directories. Note that the Python environment directory can be placed elsewhere by setting the ``IDF_PYTHON_ENV_PATH`` environment variable.
 
   - ``idf_version.txt`` — located within each specific Python environment sub-directory under ``python_env``, this file records the ESP-IDF version corresponding to that environment. The version is stored in a format like ``5.3`` to represent ESP-IDF version ``v5.3``.
+
+- ``root_managed_components`` — directory managed by ``idf-component-manager`` for components installed globally.
 - ``espidf.constraints.*.txt`` — one constraint file for each ESP-IDF release containing Python package version requirements.
 
 GitHub Assets Mirror

docs/en/contribute/esp-idf-tests-with-pytest.rst

@@ -120,6 +120,52 @@ Next, we have the environment marker:
 
 Finally, we have the test function. With a ``dut`` fixture. In single-dut test cases, the ``dut`` fixture is an instance of ``IdfDut`` class, for multi-dut test cases, it is a tuple of ``IdfDut`` instances. For more details regarding the ``IdfDut`` class, please refer to `pytest-embedded IdfDut API reference <https://docs.espressif.com/projects/pytest-embedded/en/latest/api.html#pytest_embedded_idf.dut.IdfDut>`__.
 
+Running Tests on Linux
+^^^^^^^^^^^^^^^^^^^^^^
+
+To execute a pytest case on the Linux host, set ``target`` to ``linux``.
+
+.. code-block:: python
+
+    @idf_parametrize('target', ['linux'], indirect=['target'])
+    def test_hello_world_linux(dut) -> None:
+        dut.expect('Hello world!')
+
+This is the simplest way to run the same test flow on the Linux host instead of on physical hardware.
+
+For a simple Linux-only test, setting ``target`` to ``linux`` is enough and the ``idf`` embedded services will be selected automatically. The ``pytest.mark.host_test`` marker is not required.
+
+For a mixed environment matrix, specify ``embedded_services`` manually for each case. See :ref:`Same App With Different Running Environments <pytest-same-app-different-running-environments>` for a more complex example.
+
+.. only:: TARGET_SUPPORT_QEMU
+
+    Running Tests in QEMU
+    ^^^^^^^^^^^^^^^^^^^^^
+
+    To execute a pytest case in QEMU, add the ``@pytest.mark.qemu`` marker to the test function.
+
+    .. code-block:: python
+
+        @pytest.mark.qemu
+        @idf_parametrize('target', ['esp32', 'esp32c3'], indirect=['target'])
+        def test_hello_world_qemu(dut) -> None:
+            dut.expect('Hello world!')
+
+    This is the simplest way to run the same test flow in QEMU instead of on physical hardware.
+
+    For a simple QEMU-only test, adding ``pytest.mark.qemu`` is enough and the ``idf,qemu`` embedded services will be selected automatically.
+
+    For a mixed environment matrix, specify ``embedded_services`` manually for each case. See the later section in this guide for a more complex example.
+
+    For QEMU installation and setup, refer to page :doc:`/api-guides/tools/qemu`.
+
+Deprecation of ``pytest.mark.host_test``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``pytest.mark.host_test`` is no longer needed and should not be added to new test cases.
+
+For Linux target test cases and QEMU test cases, the required behavior is handled dynamically by the test framework. In particular, the embedded services are selected automatically for simple Linux-only and QEMU-only cases.
+
 Same App With Different sdkconfig Files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -208,6 +254,49 @@ Now this test function would be replicated to 2 test cases (represented as test
 * ``esp32.foo.test_foo_bar``
 * ``esp32s2.bar.test_foo_bar``
 
+.. _pytest-same-app-different-running-environments:
+
+Same App With Different Running Environments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes the same app should be validated in different running environments, for example on the host with the Linux target, on real hardware, or in QEMU. If a single ``@pytest.mark.qemu`` test is not enough, combine ``target``, ``config``, and ``embedded_services`` in a single ``idf_parametrize`` decorator, and attach the required marker for each case.
+
+The following example is adapted from :idf_file:`components/console/test_apps/console/pytest_console.py`:
+
+.. code-block:: python
+
+    @idf_parametrize(
+        'target,config,embedded_services,markers',
+        [
+            ('linux', 'defaults', 'idf', ()),
+            ('esp32', 'defaults', 'esp,idf', (pytest.mark.generic,)),
+            ('esp32c3', 'defaults', 'esp,idf', (pytest.mark.generic,)),
+            ('esp32', 'defaults', 'idf,qemu', (pytest.mark.qemu,)),
+        ],
+        indirect=['target', 'config', 'embedded_services'],
+    )
+    def test_console_repl(dut) -> None:
+        dut.expect_exact('Press ENTER to see the list of tests')
+
+This creates four test cases for the same app:
+
+* Linux host execution with the ``idf`` service
+* ESP32 hardware execution with the ``esp,idf`` services
+* ESP32-C3 hardware execution with the ``esp,idf`` services
+* ESP32 execution in QEMU with the ``idf,qemu`` services
+
+When running locally, you can select only the environment you want:
+
+.. code-block:: shell
+
+    $ pytest --target linux
+    $ pytest -m qemu
+    $ pytest -m qemu --target esp32
+
+``pytest --target linux`` selects Linux target cases only. ``pytest -m qemu`` selects all QEMU-marked cases. ``pytest -m qemu --target esp32`` further limits the selection to QEMU cases for the ESP32 target.
+
+Use this pattern when the test logic is the same but the execution environment changes.
+
 Testing Serial Output (Expecting)
 ---------------------------------