On this page

M

bench

History
bench(name?, options?, fn): Promise
Attributes
name?:string
The benchmark name. Default: The name property of fn, or '<anonymous>' when fn has no name.
options:Object
diagnosticChannels?:Array
String diagnostics channel names, deduplicated and inherited from containing suites by union. Symbol values in the array are silently ignored. Default: [].
only?:boolean
When any benchmark or containing suite has only set, benchmarks without only in their hierarchy are skipped. Default: false.
params?:Object
String, finite number, or boolean metadata identifying this benchmark configuration. Parameter keys are sorted when constructing the stable benchmark identity. Default: An empty object.
samples?:number
The maximum number of measured callback invocations. Must be a positive 32-bit unsigned integer. The benchmark may finish earlier by calling context.done(). Default: 30.
signal:AbortSignal
Allows aborting this benchmark.
skip?:boolean | string
If truthy, the benchmark is skipped. A string is included in the result as the skip reason. Default: false.
tags?:string[]
Labels associated with the benchmark. Tags are lowercased, deduplicated, and inherited from containing suites by union. Default: [].
timeout?:number
The number of milliseconds after which the benchmark fails. Default: Infinity.
warmup?:number
The number of unreported callback invocations before measured samples. Must be a 32-bit unsigned integer. Default: 0.
fn:Function | AsyncFunction
The benchmark function. It receives a BenchContext.
Returns:Promise
Fulfilled with the benchmark result after a top-level benchmark finishes, or with undefined immediately when declared in a suite.

Warmup invocations use the same callback and timing contract as measured samples, but their samples are discarded. An exception, rejection, timeout, abort, missing timing call, or duplicate timing call stops the current benchmark. Later benchmarks continue to run.

After a timeout or abort, the runner briefly waits for asynchronous benchmark work to settle before continuing. If it remains pending, all later benchmarks that were selected to run fail without running so that their measurements cannot overlap with that work.

For each warmup and measured callback, the runner subscribes to the configured diagnostics channels. Each publication queues a context diagnostic whose message is { name, message }, containing the string channel name and the published message. Subscriptions are removed when the callback settles or is aborted.

A timeout or abort cannot interrupt synchronous JavaScript and does not forcibly cancel asynchronous work that ignores context.signal.

The benchId is based on the declaration source file, hierarchical suite and benchmark names, and canonicalized parameters. It is stable for repeated runs from the same source location, but the embedded source value is not normalized across checkout roots, module formats, operating systems, or path casing.

Execution scope is represented separately. A runId identifies one logical run, while fileRunId identifies a file runner or child execution within that run. The entryFile field records which entry-file import caused a declaration and is null for declarations made by preload modules. The same benchId can therefore occur under multiple fileRunId values when entry files use a shared declaration helper. Declaring the same benchId more than once within one file execution scope reports an error rather than merging the samples.

M

bench.skip

History
bench.skip(name?, options?, fn): void

Shorthand for bench(name, { ...options, skip: true }, fn).

M

bench.only

History
bench.only(name?, options?, fn): void

Shorthand for bench(name, { ...options, only: true }, fn).

PreviouscreateRunnerNextsuite