On this page

class TestsStream extends Readable

A successful call to run() method will return a new TestsStream object, streaming a series of events representing the execution of the tests. TestsStream will emit events, in the order of the tests definition

Some of the events are guaranteed to be emitted in the same order as the tests are defined, while others are emitted in the order that the tests execute.

The following tables summarize all events by scope.

Test scoped events are emitted once per test or suite. Most of them come in pairs: a declaration ordered event, buffered so that events are emitted in the same order as the tests are defined, and one or more corresponding execution ordered events, emitted immediately as the tests execute.

Declaration ordered (buffered)Execution ordered (immediate)
'test:start''test:enqueue' followed by 'test:dequeue'
'test:pass''test:complete' (details.passed is true)
'test:fail''test:complete' (details.passed is false)
'test:plan'
'test:diagnostic'
'test:log'

'test:log' is deliberately execution ordered only: it is the live counterpart of 'test:diagnostic''s buffered reporting.

File scoped and global events are always emitted immediately, in execution order.

File scoped events are emitted once per test file:

EventNotes
'test:stderr'Only emitted if the --test flag is passed.
'test:stdout'Only emitted if the --test flag is passed.
'test:summary'Per file, only when process isolation is used.

Global events are emitted once per test run:

EventNotes
'test:summary'The final cumulative summary.
'test:coverage'Only when code coverage is enabled.
'test:interrupted'Only when the run receives SIGINT.
'test:watch:drained'Watch mode only.
'test:watch:restarted'Watch mode only.

The root test also emits 'test:plan' and 'test:diagnostic' events at the end of the run to report run level totals.

Attributes
data:Object
summary:Object
An object containing the coverage report.
files:Array
An array of coverage reports for individual files. Each report is an object with the following schema:
path:string
The absolute path of the file.
totalLineCount:number
The total number of lines.
totalBranchCount:number
The total number of branches.
totalFunctionCount:number
The total number of functions.
coveredLineCount:number
The number of covered lines.
coveredBranchCount:number
The number of covered branches.
coveredFunctionCount:number
The number of covered functions.
coveredLinePercent:number
The percentage of lines covered.
coveredBranchPercent:number
The percentage of branches covered.
coveredFunctionPercent:number
The percentage of functions covered.
functions:Array
An array of functions representing function coverage.
name:string
The name of the function.
line:number
The line number where the function is defined.
count:number
The number of times the function was called.
branches:Array
An array of branches representing branch coverage.
line:number
The line number where the branch is defined.
count:number
The number of times the branch was taken.
lines:Array
An array of lines representing line numbers and the number of times they were covered.
line:number
The line number.
count:number
The number of times the line was covered.
thresholds:Object
An object containing whether or not the coverage for each coverage type.
function:number
The function coverage threshold.
branch:number
The branch coverage threshold.
line:number
The line coverage threshold.
totals:Object
An object containing a summary of coverage for all files.
totalLineCount:number
The total number of lines.
totalBranchCount:number
The total number of branches.
totalFunctionCount:number
The total number of functions.
coveredLineCount:number
The number of covered lines.
coveredBranchCount:number
The number of covered branches.
coveredFunctionCount:number
The number of covered functions.
coveredLinePercent:number
The percentage of lines covered.
coveredBranchPercent:number
The percentage of branches covered.
coveredFunctionPercent:number
The percentage of functions covered.
workingDirectory:string
The working directory when code coverage began. This is useful for displaying relative path names in case the tests changed the working directory of the Node.js process.
nesting:number
The nesting level of the test.

Emitted when code coverage is enabled and all tests have completed.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
details:Object
Additional execution metadata.
passed:boolean
Whether the test passed or not.
duration_ms:number
The duration of the test in milliseconds.
error:Error | undefined
An error wrapping the error thrown by the test if it did not pass.
cause:Error
The actual error thrown by the test.
type:string | undefined
The type of the test, used to denote whether this is a suite.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
name:string
The test name.
nesting:number
The nesting level of the test.
parentId:number | undefined
The testId of the enclosing test, or undefined for top-level tests. Lets custom reporters track lineage when concurrent siblings at the same nesting level interleave.
tags:string[]
The flattened lowercased tags declared on the test and its ancestor suites, in declaration order. Empty for untagged tests. See Test tags.
testId:number
A numeric identifier for this test instance, unique within the test file's process. Consistent across all events for the same test instance, enabling reliable correlation in custom reporters.
testNumber:number
The ordinal number of the test.
todo:string | boolean | undefined
Present if context.todo is called
skip:string | boolean | undefined
Present if context.skip is called

Emitted when a test completes its execution. This event is not emitted in the same order as the tests are defined. The corresponding declaration ordered events are 'test:pass' and 'test:fail'.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
name:string
The test name.
nesting:number
The nesting level of the test.
parentId:number | undefined
The testId of the enclosing test, or undefined for top-level tests. Lets custom reporters track lineage when concurrent siblings at the same nesting level interleave.
tags:string[]
The flattened lowercased tags declared on the test and its ancestor suites, in declaration order. Empty for untagged tests. See Test tags.
testId:number
A numeric identifier for this test instance, unique within the test file's process. Consistent across all events for the same test instance, enabling reliable correlation in custom reporters.
type:string
The test type. Either 'suite' or 'test'.

Emitted when a test is dequeued, right before it is executed. This event is not guaranteed to be emitted in the same order as the tests are defined. The corresponding declaration ordered event is 'test:start'.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
message:string
The diagnostic message.
nesting:number
The nesting level of the test.
level:string
The severity level of the diagnostic message. Possible values are:
'info':
Informational messages.
'warn':
Warnings.
'error':
Errors.

Emitted when context.diagnostic is called. This event is guaranteed to be emitted in the same order as the tests are defined.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
name:string
The test name.
nesting:number
The nesting level of the test.
parentId:number | undefined
The testId of the enclosing test, or undefined for top-level tests. Lets custom reporters track lineage when concurrent siblings at the same nesting level interleave.
tags:string[]
The flattened lowercased tags declared on the test and its ancestor suites, in declaration order. Empty for untagged tests. See Test tags.
testId:number
A numeric identifier for this test instance, unique within the test file's process. Consistent across all events for the same test instance, enabling reliable correlation in custom reporters.
type:string
The test type. Either 'suite' or 'test'.

Emitted when a test is enqueued for execution.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
details:Object
Additional execution metadata.
duration_ms:number
The duration of the test in milliseconds.
error:Error
An error wrapping the error thrown by the test.
cause:Error
The actual error thrown by the test.
type:string | undefined
The type of the test, used to denote whether this is a suite.
attempt:number | undefined
The attempt number of the test run, present only when using the --test-rerun-failures flag.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
name:string
The test name.
nesting:number
The nesting level of the test.
parentId:number | undefined
The testId of the enclosing test, or undefined for top-level tests. Lets custom reporters track lineage when concurrent siblings at the same nesting level interleave.
tags:string[]
The flattened lowercased tags declared on the test and its ancestor suites, in declaration order. Empty for untagged tests. See Test tags.
testId:number
A numeric identifier for this test instance, unique within the test file's process. Consistent across all events for the same test instance, enabling reliable correlation in custom reporters.
testNumber:number
The ordinal number of the test.
todo:string | boolean | undefined
Present if context.todo is called
skip:string | boolean | undefined
Present if context.skip is called

Emitted when a test fails. This event is guaranteed to be emitted in the same order as the tests are defined. The corresponding execution ordered event is 'test:complete'.

E

test:interrupted

History
Attributes
data:Object
tests:Array
An array of objects containing information about the interrupted tests.
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
name:string
The test name.
nesting:number
The nesting level of the test.

Emitted when the test runner is interrupted by a SIGINT signal (e.g., when pressing Ctrl+C). The event contains information about the tests that were running at the time of interruption.

When using process isolation (the default), the test name will be the file path since the parent runner only knows about file-level tests. When using --test-isolation=none, the actual test name is shown.

E

test:log

History
Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
data:any
The structured payload passed to context.log, or undefined if none was provided. The test runner does not interpret this value.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
message:string
The log message.
name:string
The test name.
nesting:number
The nesting level of the test.
parentId:number | undefined
The testId of the enclosing test, or undefined for top-level tests.
testId:number
A numeric identifier for the test instance that emitted the log message.

Emitted when context.log is called. Unlike 'test:diagnostic', this event is emitted immediately, in the order that the tests execute, making it suitable for reporters that render test output unbuffered.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
details:Object
Additional execution metadata.
duration_ms:number
The duration of the test in milliseconds.
type:string | undefined
The type of the test, used to denote whether this is a suite.
attempt:number | undefined
The attempt number of the test run, present only when using the --test-rerun-failures flag.
passed_on_attempt:number | undefined
The attempt number the test passed on, present only when using the --test-rerun-failures flag.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
name:string
The test name.
nesting:number
The nesting level of the test.
parentId:number | undefined
The testId of the enclosing test, or undefined for top-level tests. Lets custom reporters track lineage when concurrent siblings at the same nesting level interleave.
tags:string[]
The flattened lowercased tags declared on the test and its ancestor suites, in declaration order. Empty for untagged tests. See Test tags.
testId:number
A numeric identifier for this test instance, unique within the test file's process. Consistent across all events for the same test instance, enabling reliable correlation in custom reporters.
testNumber:number
The ordinal number of the test.
todo:string | boolean | undefined
Present if context.todo is called
skip:string | boolean | undefined
Present if context.skip is called

Emitted when a test passes. This event is guaranteed to be emitted in the same order as the tests are defined. The corresponding execution ordered event is 'test:complete'.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
nesting:number
The nesting level of the test.
count:number
The number of subtests that have ran.

Emitted when all subtests have completed for a given test. This event is guaranteed to be emitted in the same order as the tests are defined.

Attributes
data:Object
column:number | undefined
The column number where the test is defined, or undefined if the test was run through the REPL.
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation. May differ from file when the test is defined in a module imported by the entry file.
file:string | undefined
The path of the test file, undefined if test was run through the REPL.
line:number | undefined
The line number where the test is defined, or undefined if the test was run through the REPL.
name:string
The test name.
nesting:number
The nesting level of the test.
parentId:number | undefined
The testId of the enclosing test, or undefined for top-level tests. Lets custom reporters track lineage when concurrent siblings at the same nesting level interleave.
tags:string[]
The flattened lowercased tags declared on the test and its ancestor suites, in declaration order. Empty for untagged tests. See Test tags.
testId:number
A numeric identifier for this test instance, unique within the test file's process. Consistent across all events for the same test instance, enabling reliable correlation in custom reporters.

Emitted when a test starts reporting its own and its subtests status. This event is guaranteed to be emitted in the same order as the tests are defined. The corresponding execution ordered event is 'test:dequeue'.

Attributes
data:Object
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation.
file:string
The path of the test file.
message:string
The message written to stderr.

Emitted when a running test writes to stderr. This event is only emitted if --test flag is passed. This event is not guaranteed to be emitted in the same order as the tests are defined.

Attributes
data:Object
entryFile:string | undefined
The path of the test file that was executed as the entry point of the child process that emitted this event. Only present when tests run with process isolation.
file:string
The path of the test file.
message:string
The message written to stdout.

Emitted when a running test writes to stdout. This event is only emitted if --test flag is passed. This event is not guaranteed to be emitted in the same order as the tests are defined.

Attributes
data:Object
counts:Object
An object containing the counts of various test results.
cancelled:number
The total number of cancelled tests.
failed:number
The total number of failed tests.
passed:number
The total number of passed tests.
skipped:number
The total number of skipped tests.
suites:number
The total number of suites run.
tests:number
The total number of tests run, excluding suites.
todo:number
The total number of TODO tests.
topLevel:number
The total number of top level tests and suites.
duration_ms:number
The duration of the test run in milliseconds.
file:string | undefined
The path of the test file that generated the summary. If the summary corresponds to multiple files, this value is undefined.
success:boolean
Indicates whether or not the test run is considered successful or not. If any error condition occurs, such as a failing test or unmet coverage threshold, this value will be set to false.

Emitted when a test run completes. This event contains metrics pertaining to the completed test run, and is useful for determining if a test run passed or failed. If process-level test isolation is used, a 'test:summary' event is generated for each test file in addition to a final cumulative summary.

Emitted when no more tests are queued for execution in watch mode.

Emitted when one or more tests are restarted due to a file change in watch mode.

PreviousMockTimersNextgetTestContext