| name: benchmark |
| returns: void |
| description: | |
| Creates a benchmark item that will be run when the benchmark target is |
| run. The behavior of this function is identical to [[test]] |
| except for: |
| |
| * benchmark() has no `is_parallel` keyword because benchmarks are not run in parallel |
| * benchmark() does not automatically add the `MALLOC_PERTURB_` environment variable |
| |
| Defined benchmarks can be run in a backend-agnostic way by calling |
| `meson test --benchmark` inside the build dir, or by using backend-specific |
| commands, such as `ninja benchmark` or `msbuild RUN_TESTS.vcxproj`. |
| |
| notes: |
| - Prior to 0.52.0 benchmark would warn that `depends` and |
| `priority` were unsupported, this is incorrect. |
| |
| posargs: |
| name: |
| type: str |
| description: The *unique* test id |
| |
| executable: |
| type: exe | jar | external_program | file | custom_tgt | custom_idx |
| description: | |
| The program to execute. *(Since 1.4.0)* A CustomTarget is also accepted. |
| |
| kwargs: |
| args: |
| type: list[str | file | tgt] |
| description: Arguments to pass to the executable |
| |
| env: |
| type: env | list[str] | dict[str] |
| description: | |
| environment variables to set, such as `['NAME1=value1', |
| 'NAME2=value2']`, or an [[@env]] object which allows more sophisticated |
| environment juggling. *(Since 0.52.0)* A dictionary is also accepted. |
| |
| should_fail: |
| type: bool |
| default: false |
| description: | |
| when true the test is considered passed if the |
| executable returns a non-zero return value (i.e. reports an error) |
| |
| suite: |
| type: str | list[str] |
| description: | |
| `'label'` (or list of labels `['label1', 'label2']`) |
| attached to this test. The suite name is qualified by a (sub)project |
| name resulting in `(sub)project_name:label`. In the case of a list |
| of strings, the suite names will be `(sub)project_name:label1`, |
| `(sub)project_name:label2`, etc. |
| |
| timeout: |
| type: int |
| default: 30 |
| description: | |
| the amount of seconds the test is allowed to run, a test |
| that exceeds its time limit is always considered failed, defaults to |
| 30 seconds. *Since 0.57* if timeout is `<= 0` the test has infinite duration, |
| in previous versions of Meson the test would fail with a timeout immediately. |
| |
| workdir: |
| type: str |
| description: | |
| absolute path that will be used as the working directory |
| for the test |
| |
| depends: |
| type: list[build_tgt | custom_tgt] |
| since: 0.46.0 |
| description: | |
| specifies that this test depends on the specified |
| target(s), even though it does not take any of them as a command |
| line argument. This is meant for cases where test finds those |
| targets internally, e.g. plugins or globbing. Those targets are built |
| before test is executed even if they have `build_by_default : false`. |
| |
| protocol: |
| type: str |
| since: 0.50.0 |
| default: "'exitcode'" |
| description: | |
| specifies how the test results are parsed and can |
| be one of `exitcode`, `tap`, or `gtest`. For more information about test |
| harness protocol read [Unit Tests](Unit-tests.md). The following values are |
| accepted: |
| |
| - `exitcode`: the executable's exit code is used by the test harness |
| to record the outcome of the test). |
| - `tap`: [Test Anything Protocol](https://www.testanything.org/). |
| - `gtest` *(since 0.55.0)*: for Google Tests. |
| - `rust` *(since 0.56.0)*: for native rust tests |
| |
| priority: |
| type: int |
| since: 0.52.0 |
| default: 0 |
| description: | |
| specifies the priority of a test. Tests with a |
| higher priority are *started* before tests with a lower priority. |
| The starting order of tests with identical priorities is |
| implementation-defined. The default priority is 0, negative numbers are |
| permitted. |
| |
| verbose: |
| type: bool |
| since: 0.62.0 |
| default: false |
| description: | |
| if true, forces the test results to be logged as if `--verbose` was passed |
| to `meson test`. |