The node:bench module supports defining and running JavaScript benchmarks in\nthe current process. To access it:
import { bench, suite } from 'node:bench';\nconst { bench, suite } = require('node:bench');\nThis module is only available under the node: scheme.
Save the following as benchmark.mjs:
import { bench, suite } from 'node:bench';\n\nsuite('URL', () => {\n const input = 'https://example.com/a?b=c';\n\n bench('construct', {\n samples: 30,\n params: { input: 'short' },\n }, (b) => {\n const operations = 10_000;\n\n b.start();\n for (let i = 0; i < operations; i++) {\n new URL(input);\n }\n b.end(operations);\n });\n});\nRun the benchmark from the command line:
\nnode --bench benchmark.mjs\nBenchmarks are executed serially in declaration order. Declared benchmarks are\nscheduled automatically. Call run() during the same turn as the declarations\nto consume the event stream or configure filtering.\nIf an automatically scheduled run fails and run() was not called, the process\nexit code is set to 1.
Each warmup and measured sample invokes the benchmark function once with a\nfresh {BenchContext}. The function must either call context.start() and\ncontext.end(operations) exactly once, or call context.record(sample) exactly\nonce to provide an externally measured sample. Setup before start() and\ncleanup after end() are outside the measured region. Promise-returning\nfunctions are awaited.
By default, an event loop turn occurs between sample invocations. An embedded\nrunner can disable this using yieldBetweenSamples. The runner executes\nbenchmarks serially, but it does not provide process isolation. Other work in\nthe process, JIT compilation, garbage collection, CPU frequency changes, and\nsystem load can all affect results. Keep raw samples when comparing results and\ninvestigate noisy or skewed distributions rather than treating a confidence\ninterval as a pass/fail threshold.
Calling context.done() during a measured sample completes the benchmark after\nthat sample. This allows a higher-level tool to treat samples as a maximum and\nimplement a dynamic sampling policy.
The module-level declaration functions use a shared runner and schedule it\nautomatically. Higher-level tools can create isolated, explicitly started\nrunners instead:
\nimport { createRunner } from 'node:bench';\n\nconst runner = createRunner({ yieldBetweenSamples: false });\n\nrunner.bench('example', { samples: 100 }, (b) => {\n const operations = chooseOperationCount();\n b.start();\n runOperations(operations);\n const sample = b.end(operations);\n\n if (hasEnoughData(sample)) b.done();\n});\n\nfor await (const record of runner.run()) {\n // Consume structured benchmark records.\n}\nEach runner has independent declarations, hooks, filtering, and output. Unlike\nthe module-level declarations, creating a benchmark on an explicit runner does\nnot schedule execution. This allows packages to collect declarations and start\nthem later. Calling the explicit runner's run() function prevents additional\ndeclarations and a second call to run() is an error.
The --bench flag runs one or more explicit benchmark files or glob patterns:
node --bench benchmark.mjs\nnode --bench --bench-reporter=json 'benchmarks/**/*.js'\nFiles are sorted and executed serially. The default\n--bench-isolation=process mode runs each file in a separate child process and\nemits one aggregate summary. Structured events are transferred to the parent\nwithout JSON conversion, preserving BigInt durations, errors, and parameter\nvalues. Child writes to stdout and stderr are emitted as diagnostic records so\nthey do not corrupt reporter output.
--bench-isolation=none imports all files into the runner process. This mode\nhas lower startup overhead, but module, heap, and process state carry between\nfiles, and user writes share stdout and stderr with reporters.
Benchmark files passed to --bench should declare benchmarks but must not call\nrun(). The CLI supports --bench-name-pattern, --bench-samples,\n--bench-warmup, --bench-reporter, and --bench-reporter-destination. See\nthe command-line options documentation for details.
The built-in reporters are available from the scheme-only\nnode:bench/reporters module:
import { json, spec } from 'node:bench/reporters';\nconst { json, spec } = require('node:bench/reporters');\nReporter values can be passed directly to stream.compose():
import { bench, run } from 'node:bench';\nimport { spec } from 'node:bench/reporters';\nimport process from 'node:process';\n\nbench('example', (b) => {\n b.start();\n doWork();\n b.end(1);\n});\n\nrun().compose(spec).pipe(process.stdout);\nThe spec reporter buffers results and outputs a concise table containing the\nsample count, mean rate, 95% confidence interval for the mean, median rate, and\nwarnings. A coefficient of variation above 5% is reported as noisy, and an\nabsolute skewness above 1 is reported as skewed. The exact human-readable\nformat is subject to change.
The json reporter emits every lifecycle record as newline-delimited JSON.\nBigInt values, including duration_ns, are encoded as decimal strings. Errors\nare represented using their name, message, stack, code, cause, and\nerrors properties. As required by JSON, non-finite numbers are encoded as\nnull.
Custom reporters use the same composition contract. They can be transforms or\nfunctions accepted by stream.compose(). The composed readable can be piped to\nany writable destination:
import { run } from 'node:bench';\nimport process from 'node:process';\n\nasync function* names(source) {\n for await (const { type, data } of source) {\n if (type === 'bench:complete') {\n yield `${data.name}\\n`;\n }\n }\n}\n\nrun().compose(names).pipe(process.stdout);\nEach measured sample has the following properties:
\noperations <number> The positive operation count passed to context.end() or context.record().duration_ns <bigint> The measured duration in nanoseconds.rate <number> Operations per second.detail <any> The optional cloned sample detail.A completed benchmark result contains:
\nbenchId <string> The stable benchmark identity.parentId <string> | <null> The stable containing suite identity.name <string> The benchmark name.file <string> The source file.line <number> The source line.column <number> The source column.tags <string>[] The inherited canonical tags.params <Object> The canonical parameter metadata.samples <Object>[] The exact measured samples.summary <Object>\nmean <number> The arithmetic mean of per-sample rates.median <number> The median per-sample rate.min <number> The minimum per-sample rate.max <number> The maximum per-sample rate.stddev <number> The population standard deviation of rates.coefficientOfVariation <number> stddev / mean.confidenceInterval <Object> The 95% Student's t confidence interval for\nthe mean rate, with lower and upper properties.medianConfidenceInterval <Object> The 95% nonparametric confidence\ninterval for the median rate, with lower and upper properties.skewness <number> The skewness of the scaled rate histogram.Creates an explicitly started benchmark runner. Declarations made through one\nrunner do not interact with declarations made through another runner or through\nthe module-level functions. Call the returned run() function to start the\nrunner and obtain its {BenchmarksStream}.
Each runner can be started once. Its run() function accepts the same options\nas the module-level run(). run({ yieldBetweenSamples }) overrides the\nvalue passed to createRunner().
Warmup invocations use the same callback and timing contract as measured\nsamples, but their samples are discarded. An exception, rejection, timeout,\nabort, missing timing call, or duplicate timing call stops the current\nbenchmark. Later benchmarks continue to run.
\nA timeout or abort cannot interrupt synchronous JavaScript and does not forcibly\ncancel asynchronous work that ignores context.signal.
The stable benchId is based on the source file, hierarchical suite and\nbenchmark names, and canonicalized parameters. Declaring the same identity\nmore than once reports an error rather than merging the samples.
Shorthand for bench(name, { ...options, skip: true }, fn).
Shorthand for bench(name, { ...options, only: true }, fn).
Suite functions run while declarations are collected. Promise-returning suite\nfunctions are awaited before benchmark execution begins.
" }, { "textRaw": "`describe([name][, options], fn)`", "name": "describe", "type": "method", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "signatures": [ { "params": [ { "name": "name", "optional": true }, { "name": "options", "optional": true }, { "name": "fn" } ] } ], "desc": "Alias for suite().
Registers a hook that runs once before the benchmarks in the current suite.
" }, { "textRaw": "`after(fn)`", "name": "after", "type": "method", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`fn` {Function|AsyncFunction} The hook function.", "name": "fn", "type": "Function|AsyncFunction", "desc": "The hook function." } ] } ], "desc": "Registers a hook that runs once after the benchmarks in the current suite.
" }, { "textRaw": "`beforeEach(fn)`", "name": "beforeEach", "type": "method", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`fn` {Function|AsyncFunction} The hook function. It receives an object with the benchmark's `name`, `params`, and `signal`.", "name": "fn", "type": "Function|AsyncFunction", "desc": "The hook function. It receives an object with the benchmark's `name`, `params`, and `signal`." } ] } ], "desc": "Registers a hook that runs once before each complete logical benchmark in the\ncurrent suite. It does not run before every sample. Per-sample setup belongs in\nthe benchmark function before context.start() or context.record().
Registers a hook that runs once after each complete logical benchmark in the\ncurrent suite. It does not run after every sample. Per-sample cleanup belongs\nin the benchmark function after context.end() or context.record().
Returns the object-mode event stream for the in-process benchmark run. Call\nrun() during the same turn in which benchmarks are declared, before automatic\nexecution begins. Calling run() is optional when the returned stream is not\nneeded. An explicit runner created by createRunner() does not run\nautomatically, so its run() function may be called later.
import { bench, run } from 'node:bench';\n\nbench('example', { samples: 3 }, (b) => {\n b.start();\n doWork();\n b.end(1);\n});\n\nfor await (const { type, data } of run()) {\n if (type === 'bench:complete' && data.error === undefined) {\n console.log(data.name, data.summary.mean);\n }\n}\nAn instance of BenchContext is passed to every benchmark invocation. A new\ninstance is created for every warmup and measured sample.
The zero-based invocation index within the current context.phase. Warmup and\nmeasured samples have separate index sequences.
The benchmark name.
" }, { "textRaw": "{Object}", "name": "params", "type": "Object", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The benchmark's canonicalized parameter metadata.
" }, { "textRaw": "{string}", "name": "phase", "type": "string", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "desc": "The current sample phase. It is 'warmup' for an unreported warmup invocation\nand 'measurement' for a measured invocation.
An abort signal that is triggered when the benchmark is aborted, times out, or\nfinishes.
" } ], "methods": [ { "textRaw": "`context.start()`", "name": "start", "type": "method", "meta": { "added": [ "REPLACEME" ], "changes": [] }, "signatures": [ { "params": [] } ], "desc": "Starts the measured region using process.hrtime.bigint(). Calling start()\nmore than once is an error.
Ends the measured region. The end timestamp is captured before operations is\nvalidated. Calling end() before start(), calling it more than once, or\nrecording a zero-duration sample is an error. When provided, detail is cloned\nafter the end timestamp is captured, so cloning time is outside the measured\nregion.
Records a measurement made by another clock or execution environment. This is\nuseful when a higher-level tool measures work in a worker and needs to exclude\nmessage transport from the duration. record() is mutually exclusive with\nstart() and end() within one callback and must be called exactly once.
Requests successful benchmark completion after the current measured sample.\nThe callback must still call either start() and end(), or record().\nCalling done() during a warmup invocation is an error. The configured\nsamples value remains the maximum number of measured invocations if done()\nis not called.
BenchmarksStream is an object-mode <stream.Readable>. Each lifecycle record is\nboth emitted as a named event and made available on the stream as { type, data }.
The events are emitted in execution order:
\n'bench:start''bench:sample''bench:complete''bench:diagnostic''bench:summary'Every benchmark-scoped event contains benchId and parentId.\n'bench:complete' data contains a benchmark result. A failed result has an\nadditional error property and may contain samples recorded before the error.\nA skipped result has an additional skip property and an empty samples\narray. 'bench:diagnostic' reports suite and hook errors. 'bench:summary'\ncontains overall success, counts, duration_ns, and file properties. The\nfile is <string> | <null>; it is null when the summary aggregates multiple\nfiles.