fix: example with streams and when over planning

doc/api/test.md

@@ -2992,6 +2992,26 @@ test('top level test', (t) => {
 });
 ```
 
+When working with asynchronous code, the `plan` function can be used to ensure that the
+correct number of assertions are run:
+
+```js
+test('planning with streams', async (t) => {
+ function* generate() {
+ yield 'a';
+ yield 'b';
+ yield 'c';
+ }
+ const expected = ['a', 'b', 'c'];
+ t.plan(expected.length);
+ const stream = Readable.from(generate());
+ stream.on('data', (chunk) => {
+ t.assert.strictEqual(chunk, expected.shift());
+ });
+ await once(stream, 'end');
+})
+```
+
 ### `context.runOnly(shouldRunOnlyTests)`
 
 <!-- YAML

test/fixtures/test-runner/output/test-runner-plan.js

@@ -1,5 +1,7 @@
 'use strict';
 const { test } = require('node:test');
+const { Readable } = require('node:stream');
+const { once } = require('node:events');
 
 test('test planning basic', (t) => {
  t.plan(2);
@@ -19,7 +21,7 @@ test('more assertions than planned', (t) => {
 
 test('subtesting', (t) => {
  t.plan(1);
- t.test('subtest', () => {});
+ t.test('subtest', () => { });
 });
 
 test('subtesting correctly', (t) => {
@@ -32,18 +34,18 @@ test('subtesting correctly', (t) => {
 });
 
 test('correctly ignoring subtesting plan', (t) => {
-  t.plan(1);
-  t.test('subtest', (st) => {
-  st.plan(1);
-  st.assert.ok(true);
-  });
+ t.plan(1);
+ t.test('subtest', (st) => {
+ st.plan(1);
+ st.assert.ok(true);
+ });
 });
 
 test('failing planning by options', { plan: 1 }, () => {
 });
 
 test('not failing planning by options', { plan: 1 }, (t) => {
-  t.assert.ok(true);
+ t.assert.ok(true);
 });
 
 test('subtest planning by options', (t) => {
@@ -52,3 +54,24 @@ test('subtest planning by options', (t) => {
  });
 });
 
+test('failing more assertions than planned', (t) => {
+ t.plan(2);
+ t.assert.ok(true);
+ t.assert.ok(true);
+ t.assert.ok(true);
+});
+
+test('planning with streams', async (t) => {
+ function* generate() {
+ yield 'a';
+ yield 'b';
+ yield 'c';
+ }
+ const expected = ['a', 'b', 'c'];
+ t.plan(expected.length);
+ const stream = Readable.from(generate());
+ stream.on('data', (chunk) => {
+ t.assert.strictEqual(chunk, expected.shift());
+ });
+ await once(stream, 'end');
+})

test/fixtures/test-runner/output/test-runner-plan.snapshot

@@ -80,11 +80,25 @@ ok 9 - subtest planning by options
  ---
  duration_ms: *
  ...
-1..9
-# tests 13
+# Subtest: failing more assertions than planned
+not ok 10 - failing more assertions than planned
+ ---
+ duration_ms: *
+ location: '/test/fixtures/test-runner/output/test-runner-plan.js:(LINE):1'
+ failureType: 'testCodeFailure'
+ error: 'plan expected 2 assertions but received 3'
+ code: 'ERR_TEST_FAILURE'
+ ...
+# Subtest: planning with streams
+ok 11 - planning with streams
+ ---
+ duration_ms: *
+ ...
+1..11
+# tests 15
 # suites 0
-# pass 10
-# fail 3
+# pass 11
+# fail 4
 # cancelled 0
 # skipped 0
 # todo 0