1#!/usr/bin/env python3
2# vim: set syntax=python ts=4 :
3# Copyright (c) 2020 Intel Corporation
4# SPDX-License-Identifier: Apache-2.0
5"""Zephyr Test Runner (twister)
6
7Also check the "User and Developer Guides" at https://docs.zephyrproject.org/
8
9This script scans for the set of unit test applications in the git
10repository and attempts to execute them. By default, it tries to
11build each test case on one platform per architecture, using a precedence
12list defined in an architecture configuration file, and if possible
13run the tests in any available emulators or simulators on the system.
14
15Test cases are detected by the presence of a 'testcase.yaml' or a sample.yaml
16files in the application's project directory. This file may contain one or more
17blocks, each identifying a test scenario. The title of the block is a name for
18the test case, which only needs to be unique for the test cases specified in
19that testsuite meta-data. The full canonical name for each test case is <path to
20test case>/<block>.
21
22Each test block in the testsuite meta data can define the following key/value
23pairs:
24
25  tags: <list of tags> (required)
26    A set of string tags for the testsuite. Usually pertains to
27    functional domains but can be anything. Command line invocations
28    of this script can filter the set of tests to run based on tag.
29
30  skip: <True|False> (default False)
31    skip testsuite unconditionally. This can be used for broken tests.
32
33  slow: <True|False> (default False)
34    Don't build or run this test case unless --enable-slow was passed
35    in on the command line. Intended for time-consuming test cases
36    that are only run under certain circumstances, like daily
37    builds.
38
39  extra_args: <list of extra arguments>
40    Extra cache entries to pass to CMake when building or running the
41    test case.
42
43  extra_configs: <list of extra configurations>
44    Extra configuration options to be merged with a master prj.conf
45    when building or running the test case.
46
47  sysbuild: <True|False> (default False)
48    If true, build the sample using the sysbuild infrastructure. Filtering
49    will only be enabled for the main project, and is not supported for
50    other projects included by sysbuild.
51
52  build_only: <True|False> (default False)
53    If true, don't try to run the test even if the selected platform
54    supports it.
55
56  build_on_all: <True|False> (default False)
57    If true, attempt to build test on all available platforms.
58
59  depends_on: <list of features>
60    A board or platform can announce what features it supports, this option
61    will enable the test only those platforms that provide this feature.
62
63  min_ram: <integer>
64    minimum amount of RAM needed for this test to build and run. This is
65    compared with information provided by the board metadata.
66
67  min_flash: <integer>
68    minimum amount of ROM needed for this test to build and run. This is
69    compared with information provided by the board metadata.
70
71  modules: <list of modules>
72    Add list of modules needed for this sample to build and run.
73
74  timeout: <number of seconds>
75    Length of time to run test in emulator before automatically killing it.
76    Default to 60 seconds.
77
78  arch_allow: <list of arches, such as x86, arm, arc>
79    Set of architectures that this test case should only be run for.
80
81  arch_exclude: <list of arches, such as x86, arm, arc>
82    Set of architectures that this test case should not run on.
83
84  platform_allow: <list of platforms>
85    Set of platforms that this test case should only be run for.
86
87  platform_exclude: <list of platforms>
88    Set of platforms that this test case should not run on.
89
90  extra_sections: <list of extra binary sections>
91    When computing sizes, twister will report errors if it finds
92    extra, unexpected sections in the Zephyr binary unless they are named
93    here. They will not be included in the size calculation.
94
95  filter: <expression>
96    Filter whether the testsuite should be run by evaluating an expression
97    against an environment containing the following values:
98
99    { ARCH : <architecture>,
100      PLATFORM : <platform>,
101      <all CONFIG_* key/value pairs in the test's generated defconfig>,
102      <all DT_* key/value pairs in the test's generated device tree file>,
103      <all CMake key/value pairs in the test's generated CMakeCache.txt file>,
104      *<env>: any environment variable available
105    }
106
107    The grammar for the expression language is as follows:
108
109    expression ::= expression "and" expression
110                 | expression "or" expression
111                 | "not" expression
112                 | "(" expression ")"
113                 | symbol "==" constant
114                 | symbol "!=" constant
115                 | symbol "<" number
116                 | symbol ">" number
117                 | symbol ">=" number
118                 | symbol "<=" number
119                 | symbol "in" list
120                 | symbol ":" string
121                 | symbol
122
123    list ::= "[" list_contents "]"
124
125    list_contents ::= constant
126                    | list_contents "," constant
127
128    constant ::= number
129               | string
130
131
132    For the case where expression ::= symbol, it evaluates to true
133    if the symbol is defined to a non-empty string.
134
135    Operator precedence, starting from lowest to highest:
136
137        or (left associative)
138        and (left associative)
139        not (right associative)
140        all comparison operators (non-associative)
141
142    arch_allow, arch_exclude, platform_allow, platform_exclude
143    are all syntactic sugar for these expressions. For instance
144
145        arch_exclude = x86 arc
146
147    Is the same as:
148
149        filter = not ARCH in ["x86", "arc"]
150
151    The ':' operator compiles the string argument as a regular expression,
152    and then returns a true value only if the symbol's value in the environment
153    matches. For example, if CONFIG_SOC="stm32f107xc" then
154
155        filter = CONFIG_SOC : "stm.*"
156
157    Would match it.
158
159The set of test cases that actually run depends on directives in the testsuite
160files and options passed in on the command line. If there is any confusion,
161running with -v or examining the test plan report (testplan.json)
162can help show why particular test cases were skipped.
163
164To load arguments from a file, write '+' before the file name, e.g.,
165+file_name. File content must be one or more valid arguments separated by
166line break instead of white spaces.
167
168Most everyday users will run with no arguments.
169
170"""
171
172import os
173import sys
174from pathlib import Path
175
176
177ZEPHYR_BASE = os.getenv("ZEPHYR_BASE")
178if not ZEPHYR_BASE:
179    # This file has been zephyr/scripts/twister for years,
180    # and that is not going to change anytime soon. Let the user
181    # run this script as ./scripts/twister without making them
182    # set ZEPHYR_BASE.
183    ZEPHYR_BASE = str(Path(__file__).resolve().parents[1])
184
185    # Propagate this decision to child processes.
186    os.environ['ZEPHYR_BASE'] = ZEPHYR_BASE
187
188    print(f'ZEPHYR_BASE unset, using "{ZEPHYR_BASE}"')
189
190sys.path.insert(0, os.path.join(ZEPHYR_BASE, "scripts/pylib/twister/"))
191sys.path.insert(0, os.path.join(ZEPHYR_BASE, "scripts/pylib/build_helpers"))
192
193from twisterlib.environment import add_parse_arguments, parse_arguments
194from twisterlib.twister_main import main
195
196if __name__ == "__main__":
197    ret = 0
198    try:
199        parser = add_parse_arguments()
200        options = parse_arguments(parser, sys.argv[1:])
201        ret = main(options)
202    finally:
203        if (os.name != "nt") and os.isatty(1):
204            # (OS is not Windows) and (stdout is interactive)
205            os.system("stty sane <&1")
206
207    sys.exit(ret)
208