Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/test.yaml

raw
1 name: test
2 returns: void
3 description: |
4 Defines a test to run with the test harness. Takes two positional
5 arguments, the first is the name of the test and the second is the
6 executable to run. The executable can be an [[@exe]] object returned by
7 [[executable]] or an [[@external_program]] object] returned by
8 [[find_program]].
9
10 *(since 0.55.0)* When cross compiling, if an exe_wrapper is needed and
11 defined the environment variable `MESON_EXE_WRAPPER` will be set to
12 the string value of that wrapper (implementation detail: using
13 `mesonlib.join_args`). Test scripts may use this to run cross built
14 binaries. If your test needs `MESON_EXE_WRAPPER` in cross build
15 situations it is your responsibility to return code 77 to tell the
16 harness to report "skip".
17
18 By default, environment variable
19 [`MALLOC_PERTURB_`](http://man7.org/linux/man-pages/man3/mallopt.3.html)
20 is automatically set by `meson test` to a random value between 1..255.
21 This can help find memory leaks on configurations using glibc,
22 including with non-GCC compilers. However, this can have a performance
23 impact, and may fail a test due to external libraries whose internals
24 are out of the user's control. To check if this feature is causing an
25 expected runtime crash, disable the feature by temporarily setting
26 environment variable `MALLOC_PERTURB_=0`. While it's preferable to
27 only temporarily disable this check, if a project requires permanent
28 disabling of this check in meson.build do like:
29
30 ```meson
31 nomalloc = environment({'MALLOC_PERTURB_': '0'})
32
33 test(..., env: nomalloc, ...)
34 ```
35
36 By default, the environment variables `ASAN_OPTIONS`, `UBSAN_OPTIONS`,
37 and `MSAN_OPTIONS` are set to enable aborting on detected violations and to
38 give a backtrace. To suppress this, `ASAN_OPTIONS`, `UBSAN_OPTIONS`, or
39 `MSAN_OPTIONS` can be set in the environment.
40
41 In addition to running individual executables as test cases, `test()`
42 can also be used to invoke an external test harness. In this case,
43 it is best to use `verbose: true` *(since 0.62.0)* and, if supported
44 by the external harness, `protocol: 'tap'` *(since 0.50.0)*. This will
45 ensure that Meson logs each subtest as it runs, instead of including
46 the whole log at the end of the run.
47
48 Defined tests can be run in a backend-agnostic way by calling
49 `meson test` inside the build dir, or by using backend-specific
50 commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`.
51
52 posargs_inherit: benchmark
53 kwargs_inherit: benchmark
54
55 kwargs:
56 is_parallel:
57 type: bool
58 default: true
59 description: |
60 when false, specifies that no other test must be
61 running at the same time as this test