name: test
returns: void
description: |
  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_`](http://man7.org/linux/man-pages/man3/mallopt.3.html)
  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:

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

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

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

posargs_inherit: benchmark
kwargs_inherit: benchmark

kwargs:
  is_parallel:
    type: bool
    default: false
    description: |
      when false, specifies that no other test must be
      running at the same time as this test