From 5d763534d681b03351c3282acba9ace6323f9ad9 Mon Sep 17 00:00:00 2001 From: Dmitrii Golovanov Date: Sun, 23 Jun 2024 16:14:05 +0200 Subject: [PATCH] doc: twister: ztest: Add test application diagram Add a diagram to illustrate a test application's project components with relationships between Ztest and Twister objects. Signed-off-by: Dmitrii Golovanov --- .../test/figures/twister_test_project.svg | 4 +++ doc/develop/test/twister.rst | 9 ++++++ doc/develop/test/ztest.rst | 28 +++++++++++-------- 3 files changed, 30 insertions(+), 11 deletions(-) create mode 100644 doc/develop/test/figures/twister_test_project.svg diff --git a/doc/develop/test/figures/twister_test_project.svg b/doc/develop/test/figures/twister_test_project.svg new file mode 100644 index 00000000000000..f21a45c2971ae1 --- /dev/null +++ b/doc/develop/test/figures/twister_test_project.svg @@ -0,0 +1,4 @@ + + + +
Test Framework (ZTEST)
Test Framework (ZTEST)
Test Suite (ZTEST_SUITE)
Test Suite (ZTEST_SUITE)
+ suite_name = "foo_bar_feature_aspect"
+ suite_name = "foo_bar_feature_aspect"
Test (ZTEST*)
Test (ZTEST*)
+ test_name = "test_buzz_and_blink"
+ test_name = "test_buzz_and_blink"
Test Scenario
(name_section.name_subsection)
Test Scenario...

+ tags:
+ levels: 
+ filter:
+ required_*:
+ arch_*:
+ platform_*: 
+ extra_*:
+ harness:
+ harness_config:

+ tags:...
Test Scenario
(name_section.name_subsection)
Test Scenario...

+ tags:
+ levels: 
+ filter:
+ required_*:
+ arch_*:
+ platform_*: 
+ extra_*:
+ harness:
+ harness_config:

+ tags:...
tests:
tests:
Test Scenario
(name_section.name_subsection)
Test Scenario...

+ tags:
+ levels: 
+ filter:
+ required_*:
+ arch_*:
+ platform_*: 
+ extra_*:

+ harness:
+ harness_config:

+ tags:...
CMakeList.txt
CMakeList.txt
+ project(foo-bar-feature)

+ project(foo-bar-feature)
./src (Test Project Implementation)
./src (Test Project Implementation)
prj.conf
prj.conf
+ Kconfig:
+ Kconfig:
Test Application binary
Test Application binary
Twister
Twister
Test Instance
Test Instance
+ outdir
+ outdir
+ testsuite:
+ testsuite:
+ platform:
+ platform:
+ testcases: []
+ testcases: []
+ status:
+ status:
+ reason:
+ reason:
+ execution_time:
+ execution_time:
+ retries:
+ retries:
Test Suite (test specification)
Test Suite (test specification)
+ yamlfile
+ yamlfile
+ id
+ id
+ testcases: []
+ testcases: []
+ ztest_suite_names: []
+ ztest_suite_names: []
+ name
+ name
Test Case
Test Case
+ testsuite:
+ testsuite:
+ status:
+ status:
+ reason:
+ reason:
+ output:
+ output:
+ duration:
+ duration:
+ name:
+ name:
Legend:
Legend:
Test Instance (Test Application) 
Test Instance (Test Application) 
Execution time-specific Test properties
Execution time-specific Test properties
Elementary Test
Elementary Test
tests/foo/bar/feature/name_section.name_subsection
tests/foo/bar/feature/name_section.name_subsection
name_section.name_subsection.buzz_and_blink
name_section.name_subsection.buzz_and_blink
Zephyr Test Application Project (tests/foo/bar/feature)
Zephyr Test Application Project (tests/foo/bar/feature)
Test Configuration (testcase.yaml)
Test Configuration (testcase.yaml)
build & run
build & run
Twister parameters:

--arch
--platform
--level

... etc. 
Twister parameters...
select
select
ELF symbols and application log parsing
ELF symbols and application log parsingText is not SVG - cannot display \ No newline at end of file diff --git a/doc/develop/test/twister.rst b/doc/develop/test/twister.rst index de8c5a8dcced5c..a65c5593461299 100644 --- a/doc/develop/test/twister.rst +++ b/doc/develop/test/twister.rst @@ -218,6 +218,15 @@ files in the application's project directory. This test application configuration file may contain one or more entries in the tests section each identifying a test scenario. +.. _twister_test_project_diagram: + +.. figure:: figures/twister_test_project.svg + :alt: Twister and a Test applications' project. + :figclass: align-center + + Twister and a Test applications' project. + + Test application configurations are written using the YAML syntax and share the same structure as samples. diff --git a/doc/develop/test/ztest.rst b/doc/develop/test/ztest.rst index 3ef65300a3a719..31b90193785aca 100644 --- a/doc/develop/test/ztest.rst +++ b/doc/develop/test/ztest.rst @@ -215,24 +215,30 @@ function can be written as follows: Quick start - Integration testing ********************************* -A simple working base is located at :zephyr_file:`samples/subsys/testsuite/integration`. Just -copy the files to ``tests/`` and edit them for your needs. The test will then -be automatically built and run by the twister script. If you are testing -the **bar** component of **foo**, you should copy the sample folder to -``tests/foo/bar``. It can then be tested with: +A simple working base is located at :zephyr_file:`samples/subsys/testsuite/integration`. +To make a test application for the **bar** component of **foo**, you should copy the +sample folder to ``tests/foo/bar`` and edit files there adjusting for your test +application's purposes. -.. code-block:: console +To build and execute all applicable test scenarios defined in your test application +use the :ref:`Twister ` tool, for example: - ./scripts/twister -s tests/foo/bar/test-identifier +.. code-block:: console -In the example above ``tests/foo/bar`` signifies the path to the test and the -``test-identifier`` references a test scenario defined in the :file:`testcase.yaml` file. + ./scripts/twister -T tests/foo/bar/ -To run all test scenarios defined in a test application, run: +To select just one of the test scenarios, run Twister with ``--scenario`` command: .. code-block:: console - ./scripts/twister -T tests/foo/bar/ + ./scripts/twister --scenario tests/foo/bar/your.test.scenario.name + +In the command line above ``tests/foo/bar`` is the path to your test application and +``your.test.scenario.name`` references a test scenario defined in :file:`testcase.yaml` +file, which is like ``sample.testing.ztest`` in the boilerplate test suite sample. + +See :ref:`Twister test project diagram ` for more details +on how Twister deals with Ztest application. The sample contains the following files: