| 1 |
name: benchmark |
| 2 |
returns: void |
| 3 |
description: | |
| 4 |
Creates a benchmark item that will be run when the benchmark target is |
| 5 |
run. The behavior of this function is identical to [[test]] |
| 6 |
except for: |
| 7 |
|
| 8 |
* benchmark() has no `is_parallel` keyword because benchmarks are not run in parallel |
| 9 |
* benchmark() does not automatically add the `MALLOC_PERTURB_` environment variable |
| 10 |
|
| 11 |
Defined benchmarks can be run in a backend-agnostic way by calling |
| 12 |
`meson test --benchmark` inside the build dir, or by using backend-specific |
| 13 |
commands, such as `ninja benchmark` or `msbuild RUN_TESTS.vcxproj`. |
| 14 |
|
| 15 |
notes: |
| 16 |
- Prior to 0.52.0 benchmark would warn that `depends` and |
| 17 |
`priority` were unsupported, this is incorrect. |
| 18 |
|
| 19 |
posargs: |
| 20 |
name: |
| 21 |
type: str |
| 22 |
description: The *unique* test id |
| 23 |
|
| 24 |
executable: |
| 25 |
type: exe | jar | external_program | file | custom_tgt | custom_idx |
| 26 |
description: | |
| 27 |
The program to execute. *(Since 1.4.0)* A CustomTarget is also accepted. |
| 28 |
|
| 29 |
kwargs: |
| 30 |
args: |
| 31 |
type: list[str | file | build_tgt | custom_tgt | custom_idx | external_program] |
| 32 |
description: Arguments to pass to the executable |
| 33 |
|
| 34 |
env: |
| 35 |
type: env | list[str] | dict[str] |
| 36 |
description: | |
| 37 |
environment variables to set, such as `['NAME1=value1', |
| 38 |
'NAME2=value2']`, or an [[@env]] object which allows more sophisticated |
| 39 |
environment juggling. *(Since 0.52.0)* A dictionary is also accepted. |
| 40 |
|
| 41 |
should_fail: |
| 42 |
type: bool |
| 43 |
default: false |
| 44 |
description: | |
| 45 |
when true the test is considered passed if the |
| 46 |
executable returns a non-zero return value (i.e. reports an error) |
| 47 |
|
| 48 |
suite: |
| 49 |
type: str | list[str] |
| 50 |
description: | |
| 51 |
`'label'` (or list of labels `['label1', 'label2']`) |
| 52 |
attached to this test. The suite name is qualified by a (sub)project |
| 53 |
name resulting in `(sub)project_name:label`. In the case of a list |
| 54 |
of strings, the suite names will be `(sub)project_name:label1`, |
| 55 |
`(sub)project_name:label2`, etc. |
| 56 |
|
| 57 |
timeout: |
| 58 |
type: int |
| 59 |
default: 30 |
| 60 |
description: | |
| 61 |
the amount of seconds the test is allowed to run, a test |
| 62 |
that exceeds its time limit is always considered failed, defaults to |
| 63 |
30 seconds. *Since 0.57* if timeout is `<= 0` the test has infinite duration, |
| 64 |
in previous versions of Meson the test would fail with a timeout immediately. |
| 65 |
|
| 66 |
workdir: |
| 67 |
type: str |
| 68 |
description: | |
| 69 |
absolute path that will be used as the working directory |
| 70 |
for the test |
| 71 |
|
| 72 |
depends: |
| 73 |
type: list[build_tgt | custom_tgt] |
| 74 |
since: 0.46.0 |
| 75 |
description: | |
| 76 |
specifies that this test depends on the specified |
| 77 |
target(s), even though it does not take any of them as a command |
| 78 |
line argument. This is meant for cases where test finds those |
| 79 |
targets internally, e.g. plugins or globbing. Those targets are built |
| 80 |
before test is executed even if they have `build_by_default : false`. |
| 81 |
|
| 82 |
protocol: |
| 83 |
type: str |
| 84 |
since: 0.50.0 |
| 85 |
default: "'exitcode'" |
| 86 |
description: | |
| 87 |
specifies how the test results are parsed and can |
| 88 |
be one of `exitcode`, `tap`, or `gtest`. For more information about test |
| 89 |
harness protocol read [Unit Tests](Unit-tests.md). The following values are |
| 90 |
accepted: |
| 91 |
|
| 92 |
- `exitcode`: the executable's exit code is used by the test harness |
| 93 |
to record the outcome of the test). |
| 94 |
- `tap`: [Test Anything Protocol](https://www.testanything.org/). |
| 95 |
- `gtest` *(since 0.55.0)*: for Google Tests. |
| 96 |
- `rust` *(since 0.56.0)*: for native rust tests |
| 97 |
|
| 98 |
priority: |
| 99 |
type: int |
| 100 |
since: 0.52.0 |
| 101 |
default: 0 |
| 102 |
description: | |
| 103 |
specifies the priority of a test. Tests with a |
| 104 |
higher priority are *started* before tests with a lower priority. |
| 105 |
The starting order of tests with identical priorities is |
| 106 |
implementation-defined. The default priority is 0, negative numbers are |
| 107 |
permitted. |
| 108 |
|
| 109 |
verbose: |
| 110 |
type: bool |
| 111 |
since: 0.62.0 |
| 112 |
default: false |
| 113 |
description: | |
| 114 |
if true, forces the test results to be logged as if `--verbose` was passed |
| 115 |
to `meson test`. |