1.. _definition_and_criteria:
2
3Sample Definition and Criteria
4##############################
5
6Definition
7==========
8
9A sample is a concise Zephyr application that provides an accessible overview of one or
10more features, subsystems, or modules. This includes kernel services, drivers, protocols, etc.
11Samples should be limited in scope and should focus only on demonstrating non-trivial or
12essential aspects of the subsystem(s) or module(s) being highlighted.
13
14Sample Criteria
15===============
16
171. Samples must not be used as a testcase.
18++++++++++++++++++++++++++++++++++++++++++
19  * The primary purpose of a sample is to provide a reference to the user.
20  * Samples must not use Zephyr's testing framework.
21
22    * Must not use :kconfig:option:`CONFIG_ZTEST` or :kconfig:option:`CONFIG_ZTEST_NEW_API`.
23    * Must not use zasserts in samples.
24
25  * If a sample can provide output that can be verified, then output should be evaluated against
26    expected value to have some level of testing for the sample itself.
27    Refer to :zephyr_file:`doc/develop/test/twister.rst` for more details.
28  * Samples are optional.
29
302. Twister should be able to build every sample.
31++++++++++++++++++++++++++++++++++++++++++++++++
32  * Every sample must have a YAML file. Reference: :zephyr_file:`doc/develop/test/twister.rst`.
33
34    **For example:**
35
36    .. code-block:: yaml
37
38      tests:
39        sample.kernel.cond_var:
40          integration_platforms:
41            - native_posix
42          tags: kernel condition_variables
43          harness: console
44          harness_config:
45            type: one_line
46            regex:
47              - ".*Waited and joined with 3 threads"
48
49  **Guidelines for Samples:**
50    * Minimize the use of ``platform_allow`` and architecture filters.
51    * Do not mark the test as build only unless necessary.
52    * Any test case-specific configuration options are added using ``extra_args`` or
53      ``extra_configs`` options in the YAML file. The `prj.conf` file should have the in-common
54      configuration options.
55    * The sample itself can be evaluated using multiple configurations in the sample's YAML file.
56      For example, the sample is used to run with different logging modes using multiple scenarios
57      in ``samples/subsys/logging/syst``.
58    * Sample output can be validated leveraging the ``harness_config`` regex option,
59      wherever applicable.
60
613. Samples should target multiple platforms and architectures.
62++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
63  * Minimize the use of ``platform_allow`` and architecture filters as it limits the scope
64    of testing to the mentioned platforms and architectures.
65    Reference: :zephyr_file:`doc/develop/test/twister.rst`
66  * Make use of ``integration_platforms`` to limit the scope when there are timing or
67    resource constraints.
68  * Make the sample as generic as possible. Avoid making a sample platform specific unless it is
69    for particular hardware.
70
714. A sample should provide sufficient coverage of a subsystem, feature, or module.
72++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
73  **DO's:**
74    * Cover the most common and important use cases of the functionality.
75    * Keep the code simple and easy to read. Example: :zephyr_file:`samples/philosophers`.
76
77  **DONT's:**
78    * Samples must not test the negative or edge case behaviors.
79    * Must not be unit tests.
80
815. Samples must be documented.
82++++++++++++++++++++++++++++++
83  * Samples must have a ``README.rst`` file in the samples folder.
84    Example: ``samples/subsys/foo/README.rst``. clearly explaining the purpose of the sample, its
85    HW requirements, and the expected sample output, if applicable.
86  * Ensure that the ``README.rst`` file is accessible in the sample hierarchy starting at
87    ``samples/index.rst``.
88
89  **README Template:**
90    * Overview, if applicable.
91    * SW/HW requirements
92    * Building & Running instructions
93    * Sample output, if applicable.
94
95
96As a starting point, this sample is a good example to refer to
97:zephyr_file:`samples/kernel/condition_variables/condvar`.
98