runFile

runFile(path, options?): BenchmarksStream

Runs exactly one benchmark module in a fresh child process and returns its object-mode event stream. A relative path is resolved from the current working directory when runFile() is called. path is not interpreted as a glob. Unless the signal is aborted or the stream is destroyed before startup, every call uses a new child. Input discovery, ordering, concurrency, retries, and multi-file scheduling remain the caller's responsibility.

When the Permission Model is enabled, the caller must have file system read access to path and permission to create child processes.

Records use advanced child process serialization, preserving supported structured values such as bigint and errors. Child writes to stdout and stderr become 'bench:diagnostic' records. A permission failure, module loading error, abnormal child exit, or cancellation also emits an error diagnostic and produces a terminal 'bench:summary' whose success property is false; these execution failures do not error the stream. If module evaluation fails after declaring benchmarks, those declarations still run before the unsuccessful summary.

env, effective inherited options, and an explicitly provided execArgv are copied when runFile() is called. The runner removes NODE_OPTIONS, replaces IPC-related environment variables, and sets its private child-context, run identity, and file identity variables, overriding properties with those names in env. Pass child Node.js options through execArgv, not NODE_OPTIONS. Standard child_process environment propagation still applies, including NODE_V8_COVERAGE, permission-model options, and required z/OS variables. Aborting signal before the child starts produces an AbortError diagnostic without spawning it. Aborting during execution sends SIGTERM to the child and escalates to SIGKILL if it does not exit. Destroying the returned stream follows the same termination procedure.