doc: add test reporter event lifecycle diagram

[Han5991]

Adds an "Event lifecycle" section under Class: TestsStream with an ASCII diagram showing how reporter events relate: declaration-order events vs their execution-order twins (test:dequeue / test:complete), the leaf vs suite flow, and the run-level finale.

Fixes: #51908

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[atlowChemi]

Ping @MoLow
You recently fixed some bugs around the order of the events, can you also have a look?

[trivikr]

This needs a rebase to resolve conflicts in doc/api/test.md

[Han5991]

@atlowChemi

I pushed to resolve the issue, so please approve it again.

[atlowChemi]

@Han5991 this mostly LGTM. Should this also mention test:interrupted?

[Han5991]

@Han5991 this mostly LGTM. Should this also mention test:interrupted?

@atlowChemi
It would be good to add that! I've added it.

[nodejs-github-bot]

Commit Queue failed

   ⚠  Found Fixes: https://github.com/nodejs/node/issues/51908, skipping..
     ⚠  0:50     Title should be <= 50 columns.            title-length

The pull request was removed from the Commit Queue and labeled commit-queue-failed PRs whose Commit Queue landing failed and need manual intervention before retrying. . After resolving the failure, remove that label and add commit-queue PRs queued for automated landing through the Commit Queue. to retry.

Full Commit Queue output

- Loading data for nodejs/node/pull/63780
✔  Done loading data for nodejs/node/pull/63780
----------------------------------- PR info ------------------------------------
Title      doc: add test reporter event lifecycle diagram (#63780)
Author     sangwook <rewq5991@gmail.com> (@Han5991)
Branch     Han5991:doc/test-reporter-events-lifecycle -> nodejs:main
Labels     doc, commit-queue, commit-queue-rebase, test_runner
Commits    3
 - doc: add test reporter event lifecycle diagram
 - doc: mention test:interrupted in event lifecycle diagram
 - doc: re-trigger CI
Committers 1
 - sangwook <rewq5991@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63780
Fixes: https://github.com/nodejs/node/issues/51908
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/63780
Fixes: https://github.com/nodejs/node/issues/51908
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Sun, 07 Jun 2026 02:36:35 GMT
   ✔  Approvals: 1
   ✔  - Chemi Atlow (@atlowChemi): https://github.com/nodejs/node/pull/63780#pullrequestreview-5030340192
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 63780
From https://github.com/nodejs/node
 * branch                  refs/pull/63780/merge -> FETCH_HEAD
✔  Fetched commits as 7b6b21a8aaea..8577f352d40a
--------------------------------------------------------------------------------
[main abcc22466c] doc: add test reporter event lifecycle diagram
 Author: sangwook <rewq5991@gmail.com>
 Date: Sun Jun 7 11:35:37 2026 +0900
 1 file changed, 59 insertions(+)
[main dd00d989a2] doc: mention test:interrupted in event lifecycle diagram
 Author: sangwook <rewq5991@gmail.com>
 Date: Tue Aug 25 20:42:36 2026 +0900
 1 file changed, 9 insertions(+)
[main 8d2117c630] doc: re-trigger CI
 Author: sangwook <rewq5991@gmail.com>
 Date: Tue Aug 25 22:42:49 2026 +0900
   ✔  Patches applied
There are 3 commits in the PR. Attempting autorebase.
(node:422) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
Rebasing (2/4)
Executing: git node land --amend --yes
   ⚠  Found Fixes: https://github.com/nodejs/node/issues/51908, skipping..
--------------------------------- New Message ----------------------------------
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: https://github.com/nodejs/node/issues/51908
Signed-off-by: sangwook <rewq5991@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63780
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
--------------------------------------------------------------------------------
[detached HEAD 814dae8e17] doc: add test reporter event lifecycle diagram
 Author: sangwook <rewq5991@gmail.com>
 Date: Sun Jun 7 11:35:37 2026 +0900
 1 file changed, 59 insertions(+)
Rebasing (3/4)
Rebasing (4/4)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: mention test:interrupted in event lifecycle diagram

The diagram only covered the normal path, ending at test:summary. Add an
INTERRUPTION branch so the abnormal path is covered too: on SIGINT the run
exits before the buffered declaration ordered events are flushed, so neither
the run level finale nor the interrupted tests' own results are emitted.

Signed-off-by: sangwook <rewq5991@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63780
Fixes: https://github.com/nodejs/node/issues/51908
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
--------------------------------------------------------------------------------
[detached HEAD e6f3f4c758] doc: mention test:interrupted in event lifecycle diagram
 Author: sangwook <rewq5991@gmail.com>
 Date: Tue Aug 25 20:42:36 2026 +0900
 1 file changed, 9 insertions(+)
Successfully rebased and updated refs/heads/main.
--------------------------------------------------------------------------------
  ✔  814dae8e176aa54b77d4a779e9c12e38d454a1c0
     ✔  0:0      no Assisted-by metadata                   assisted-by-is-trailer
     ✔  0:0      no Co-authored-by metadata                co-authored-by-is-trailer
     ✔  7:7      Valid fixes URL.                          fixes-url
     ✔  0:0      blank line after title                    line-after-title
     ✔  0:0      line-lengths are valid                    line-length
     ✔  0:0      metadata is at end of message             metadata-end
     ✔  9:8      PR-URL is valid.                          pr-url
     ✔  0:0      reviewers are valid                       reviewers
     ✔  0:0      has valid Signed-off-by                   signed-off-by
     ✔  0:0      valid subsystems                          subsystem
     ✔  0:0      Title is formatted correctly.             title-format
     ✔  0:0      Title is <= 50 columns.                   title-length
  ✖  e6f3f4c7588ed1f5f3713ca96279cae58448715c
     ✔  0:0      no Assisted-by metadata                   assisted-by-is-trailer
     ✔  0:0      no Co-authored-by metadata                co-authored-by-is-trailer
     ✔  8:7      Valid fixes URL.                          fixes-url
     ✔  0:0      blank line after title                    line-after-title
     ✖  7:72     Line should be <= 72 columns.             line-length
     ✖  8:72     Line should be <= 72 columns.             line-length
     ✔  0:0      metadata is at end of message             metadata-end
     ✔  7:8      PR-URL is valid.                          pr-url
     ✔  0:0      reviewers are valid                       reviewers
     ✔  0:0      has valid Signed-off-by                   signed-off-by
     ✔  0:0      valid subsystems                          subsystem
     ✔  0:0      Title is formatted correctly.             title-format
     ⚠  0:50     Title should be <= 50 columns.            title-length
   ℹ  Please fix the commit message and try again.
Please manually ammend the commit message, by running
`git commit --amend`
Once commit message is fixed, finish the landing command running
`git node land --continue`

View workflow run

[Han5991]

@atlowChemi

A "commit-queue-failed" error occurred, so I have updated the commit message. Please approve and merge.

[atlowChemi]

Landed in 29c517f