diff mbox series

[yocto-docs,v3] dev-manual: Document yocto-check-layer --run-tests

Message ID 20261119124140.2024131-1-otavio@ossystems.tech
State New
Headers show
Series [yocto-docs,v3] dev-manual: Document yocto-check-layer --run-tests | expand

Commit Message

Otavio Salvador Nov. 19, 2026, 12:41 p.m. UTC
yocto-check-layer can now run a subset of its tests with --run-tests,
for example to split a long check of a BSP layer over several runs.
Document the option, and that a PASS from such a run doesn't make a
layer Yocto Project Compatible: that needs a single run with all the
tests and, for a BSP layer, all its machines.

AI-Generated: Claude Code, Opus 5.5
Signed-off-by: Otavio Salvador <otavio@ossystems.tech>
---
Changes in v3:
- Explain <module>[.<class>[.<name>]], list the module and class of each
  test file with a link to it, and add an example running single tests
  (Quentin Schulz).

Changes in v2:
- Use the same address for the author and the Signed-off-by.

 documentation/dev-manual/layers.rst | 36 +++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
diff mbox series

Patch

diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index 5c8bf32b4..66877089d 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -405,6 +405,42 @@  argument should be passed as part of the command::
 These machines are the ones present in your BSP layer, in the ``conf/machine/``
 directory.
 
+To run only some of the tests, for example to split a long check over
+several runs, pass them to the ``--run-tests`` argument as
+``<module>[.<class>[.<name>]]``: a module runs all its tests, a module and
+a class all the tests of that class, and a full name a single test. The
+modules are the files in the :oe_git:`scripts/lib/checklayer/cases
+</openembedded-core/tree/scripts/lib/checklayer/cases>` directory, each
+with one class:
+
+-  ``common``: ``CommonCheckLayer``, in :oe_git:`common.py
+   </openembedded-core/tree/scripts/lib/checklayer/cases/common.py>`.
+
+-  ``bsp``: ``BSPCheckLayer``, in :oe_git:`bsp.py
+   </openembedded-core/tree/scripts/lib/checklayer/cases/bsp.py>`.
+
+-  ``distro``: ``DistroCheckLayer``, in :oe_git:`distro.py
+   </openembedded-core/tree/scripts/lib/checklayer/cases/distro.py>`.
+
+For example, to run all the BSP tests::
+
+   $ source oe-init-build-env
+   $ yocto-check-layer --run-tests bsp --machines <machine1> <machine2> ... -- your_layer_directory
+
+Or to run only the ``test_world`` test listed below as
+``common.test_world``, and the ``test_machine_signatures`` one::
+
+   $ source oe-init-build-env
+   $ yocto-check-layer --run-tests common.CommonCheckLayer.test_world \
+         bsp.BSPCheckLayer.test_machine_signatures \
+         --machines <machine1> <machine2> ... -- your_layer_directory
+
+.. note::
+
+   A "PASS" from such a run only covers the tests and machines it ran. A
+   layer is Yocto Project Compatible only if a single run with all the
+   tests, and with all the machines of a BSP layer, passes.
+
 Entering the command causes the script to determine the type of layer
 and then to execute a set of specific tests against the layer.