Skip to content

Commit 91132e3

Browse files
Han5991aduh95
authored andcommitted
doc: add test reporter event lifecycle diagram
Document the lifecycle of node:test reporter events under Class: TestsStream, with an ASCII diagram that distinguishes declaration-order events from their execution-order twins (test:dequeue/test:complete), the leaf vs suite flow, and the run-level finale. Fixes: #51908 Signed-off-by: sangwook <rewq5991@gmail.com> PR-URL: #63780 Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
1 parent 358bf6a commit 91132e3

1 file changed

Lines changed: 68 additions & 0 deletions

File tree

β€Ždoc/api/test.mdβ€Ž

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3568,6 +3568,74 @@ Global events are emitted once per test run:
35683568
The root test also emits [`'test:plan'`][] and [`'test:diagnostic'`][] events
35693569
at the end of the run to report run level totals.
35703570

3571+
### Event lifecycle
3572+
3573+
The tables above group the events; the diagram below places them on a
3574+
timeline. The declaration ordered events form the main spine, buffered so that
3575+
a reporter sees them in source order, while each execution ordered twin is
3576+
emitted immediately, when the work actually happens. In particular,
3577+
[`'test:start'`][] marks when a test begins _reporting_ its own and its
3578+
subtests' status, not when its body begins executing; that moment is
3579+
[`'test:dequeue'`][].
3580+
3581+
```text
3582+
node:test reporter event lifecycle
3583+
main spine = DECLARATION order (buffered; matches source order)
3584+
right side = EXECUTION order (emitted immediately); β—„ marks each twin
3585+
3586+
LEAF TEST
3587+
─────────
3588+
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” test:enqueue
3589+
β”‚ test:start β”‚ ◄──── twins ──── (queued for execution;
3590+
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ type: 'suite' | 'test')
3591+
β”‚ begins REPORTING test:dequeue
3592+
β”‚ (not the start of (about to run; emitted right
3593+
β”‚ the test body) before the test body runs)
3594+
β”‚
3595+
β”‚ [ between the twins, on the execution timeline, the test
3596+
β”‚ body runs: context.log() emits test:log live, and
3597+
β”‚ test:stdout / test:stderr stream with --test ]
3598+
β”‚
3599+
β–Ό
3600+
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
3601+
β”‚ test:pass β”‚ test:fail β”‚ ◄──── twin ──── test:complete
3602+
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ result (details.passed says which)
3603+
β”‚
3604+
β–Ό
3605+
test:diagnostic the test's own context.diagnostic() messages,
3606+
buffered while it runs, flushed after its result
3607+
3608+
3609+
SUITE / PARENT TEST (each subtest is the whole LEAF flow above)
3610+
───────────────────
3611+
test:start ─► [ full flow of each subtest ... ] ─►
3612+
test:plan (count = subtests) ─► test:pass β”‚ test:fail ─►
3613+
test:diagnostic
3614+
3615+
3616+
RUN-LEVEL FINALE (root, after all top-level tests)
3617+
────────────────
3618+
test:plan top-level count
3619+
β”‚
3620+
β–Ό
3621+
test:diagnostic x N tests, suites, pass, fail, cancelled,
3622+
β”‚ skipped, todo, duration_ms (+ coverage errors)
3623+
β–Ό
3624+
test:coverage only if coverage is enabled
3625+
β”‚
3626+
β–Ό
3627+
test:summary ─► stream ends
3628+
3629+
3630+
INTERRUPTION (SIGINT, e.g. Ctrl+C, while tests are still running)
3631+
────────────
3632+
test:interrupted the innermost tests still running at that moment
3633+
β”‚ (not emitted if none were running)
3634+
β–Ό
3635+
the run exits immediately β€” the buffered spine never flushes, so
3636+
neither the finale above nor those tests' own results are emitted
3637+
```
3638+
35713639
### Event: `'test:coverage'`
35723640

35733641
* `data` {Object}

0 commit comments

Comments
Β (0)