rules/cli.md
GitHubCommand-line runner and reporters
node --experimental-bench --bench file.mjs 'dir/**/*.bench.mjs'
- You need at least one file or glob. Quote globs. Files are sorted and run serially.
- Every
--bench*flag needs--experimental-bench, otherwise you get "--experimental-bench is required to use --bench or related options". --benchcan't be combined with--test,--watch,--watch-path,--check,--evalor--interactive(verified for test, watch, check, eval and interactive).- Exit code
1if any benchmark fails (verified).
| Flag | Versions | Meaning |
|---|---|---|
--bench-samples=N |
v26.9.0 | overrides samples for every benchmark (1 to 2^32-1) |
--bench-warmup=N |
v26.9.0 | overrides warmup (0 to 2^32-1) |
--bench-name-pattern=re |
v26.9.0 | runs matching hierarchical names; the others are reported as skipped ('name pattern') |
--bench-isolation=process|none |
v26.9.0 | process (default): one child per file. none: all files in one process, sharing state and stdout |
--bench-reporter=spec|json|<module> |
v26.9.0 | repeatable; the default is spec |
--bench-reporter-destination=stdout|stderr|<path> |
v26.9.0 | one per reporter when more than one is given |
--bench-gc=none|once|sample |
added: REPLACEME (main only) |
overrides every benchmark's gc. With process isolation it adds --expose-gc to children. With none you pass --expose-gc yourself (verified) |
Process isolation (verified): a child's console.log becomes a
bench:diagnostic record with stream: 'stdout'. Each file gets its own
fileRunId. Plans for a later file appear after the earlier file finishes.
Options such as --expose-gc given to the parent are inherited by the
children.
Reporters
specprints a table of samples, mean rate, 95% CI, median and warnings.noisymeans CV > 5%,skewedmeans |skewness| > 1, andimplausiblemeans a median ≥ 1 op/ns, which usually indicates eliminated work. On main the table starts with an environment header (node, V8, CPU, memory, load, execArgv). v26.13.0 has no header.jsonwrites NDJSON{ type, data }. Bigints such asduration_nsbecome decimal strings, and non-finite numbers becomenull. On main the first record isbench:environment. v26.13.0 doesn't emit it.- Programmatic use:
import { spec, json } from 'node:bench/reporters', thenrun().compose(spec).pipe(process.stdout). - Custom reporter: a module whose default export is an async generator
function
async function* (source) { for await (const { type, data } of source) yield '...'; }, passed as--bench-reporter=./reporter.mjs. - Observed on main ab476eccd03: with
--bench-reporter=./custom.mjs --bench-reporter=json(custom first), the json destination stayed empty. With json listed first, both reporters wrote output.
runFile(path[, { env, execArgv, signal }]) (v26.9.0)
This runs one module in a new child process and returns a
BenchmarksStream. Records keep bigint values because they use advanced
serialization. execArgv replaces the inherited options and must not contain
benchmark runner flags: passing --experimental-bench throws
ERR_INVALID_ARG_VALUE (verified). NODE_OPTIONS is removed, so pass options
through execArgv. A load error in the module becomes a bench:diagnostic
plus bench:summary { success: false }. It does not throw (verified on v26.13
with a missing export). Globbing, ordering and retries are up to the caller.