test()

Defines a test to run with the test harness. Takes two positional arguments, the first is the name of the test and the second is the executable to run. The executable can be an exe object returned by executable() or an external_program object] returned by find_program().

(since 0.55.0) When cross compiling, if an exe_wrapper is needed and defined the environment variable MESON_EXE_WRAPPER will be set to the string value of that wrapper (implementation detail: using mesonlib.join_args). Test scripts may use this to run cross built binaries. If your test needs MESON_EXE_WRAPPER in cross build situations it is your responsibility to return code 77 to tell the harness to report "skip".

By default, environment variable MALLOC_PERTURB_ is automatically set by meson test to a random value between 1..255. This can help find memory leaks on configurations using glibc, including with non-GCC compilers. However, this can have a performance impact, and may fail a test due to external libraries whose internals are out of the user's control. To check if this feature is causing an expected runtime crash, disable the feature by temporarily setting environment variable MALLOC_PERTURB_=0. While it's preferable to only temporarily disable this check, if a project requires permanent disabling of this check in meson.build do like:

nomalloc = environment({'MALLOC_PERTURB_': '0'})

test(..., env: nomalloc, ...)

By default, the environment variables ASAN_OPTIONS, UBSAN_OPTIONS, and MSAN_OPTIONS are set to enable aborting on detected violations and to give a backtrace. To suppress this, ASAN_OPTIONS, UBSAN_OPTIONS, or MSAN_OPTIONS can be set in the environment.

In addition to running individual executables as test cases, test() can also be used to invoke an external test harness. In this case, it is best to use verbose: true (since 0.62.0) and, if supported by the external harness, protocol: 'tap' (since 0.50.0). This will ensure that Meson logs each subtest as it runs, instead of including the whole log at the end of the run.

Defined tests can be run in a backend-agnostic way by calling meson test inside the build dir, or by using backend-specific commands, such as ninja test or msbuild RUN_TESTS.vcxproj.

# Defines a test to run with the test harness
void test(
  str                                                           name,           # The *unique* test id
  exe | jar | external_program | file | custom_tgt | custom_idx executable,     # The program to execute

  # Keyword arguments:
  args        : array[str | file | tgt | external_program]  # Arguments to pass to the executable
  depends     : array[build_tgt | custom_tgt]               # specifies that this test depends on the specified
  env         : env | array[str] | dict[str]                # environment variables to set, such as `['NAME1=value1',
  is_parallel : bool                                        # when false, specifies that no other test must be
  priority    : int                                         # specifies the priority of a test
  protocol    : str                                         # specifies how the test results are parsed and can
  should_fail : bool                                        # when true the test is considered passed if the
  suite       : str | array[str]                            # `'label'` (or array of labels `['label1', 'label2']`)
  timeout     : int                                         # the amount of seconds the test is allowed to run, a test
  verbose     : bool                                        # if true, forces the test results to be logged as if `--verbose` was passed
  workdir     : str                                         # absolute path that will be used as the working directory
)

Arguments

The function test() accepts the following positional arguments:

Finally, test() accepts the following keyword arguments: