| 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 |