fix: example with streams and when over planning

Author: marco-ippolito

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