BenchContext

An instance of BenchContext is passed to every benchmark invocation. A new instance is created for every warmup and measured sample.

The zero-based invocation index within the current context.phase. Warmup and measured samples have separate index sequences.

The benchmark name.

The benchmark's canonicalized parameter metadata.

The current sample phase. It is 'warmup' for an unreported warmup invocation and 'measurement' for a measured invocation.

An abort signal that is triggered when the benchmark is aborted, times out, or finishes.

context.start(): void

Starts the measured region using process.hrtime.bigint(). Calling start() more than once is an error.

context.end(operations, options?): Object

Ends the measured region. The end timestamp is captured before operations is validated. Calling end() before start(), calling it more than once, or recording a zero-duration sample is an error. When provided, detail is cloned after the end timestamp is captured, so cloning time is outside the measured region.

context.record(sample): Object

Records a measurement made by another clock or execution environment. This is useful when a higher-level tool measures work in a worker and needs to exclude message transport from the duration. record() is mutually exclusive with start() and end() within one callback and must be called exactly once.

context.diagnostic(message, options?): undefined

Queues a diagnostic associated with the current benchmark, phase, and sample index. Multiple diagnostics preserve call order. They are emitted after the sample callback settles and before that sample's 'bench:sample' event. Warmup diagnostics are emitted even though warmup samples are not. Diagnostics queued before a callback failure are emitted before the failed 'bench:complete' event and do not themselves cause the benchmark to fail. If a timeout or abort wins before the callback settles, queued diagnostics might not be emitted.

The message and detail are cloned synchronously. Options are also validated synchronously. Calling diagnostic() between context.start() and context.end() therefore includes that work in the measured duration. Invalid arguments or an uncloneable message or detail violate the sample contract.

context.done(): void

Requests successful benchmark completion after the current measured sample. The callback must still call either start() and end(), or record(). Calling done() during a warmup invocation is an error. The configured samples value remains the maximum number of measured invocations if done() is not called.