TestContext.plan method | Node.js node:test module | Bun

This function is used to set the number of assertions and subtests that are expected to run within the test. If the number of assertions and subtests that run does not match the expected count, the test will fail.

Note: To make sure assertions are tracked, t.assert must be used instead of assert directly.

test('top level test', (t) => {
t.plan(2);
t.assert.ok('some relevant assertion here');
t.test('subtest', () => {});
});

When working with asynchronous code, the plan function can be used to ensure that the correct number of assertions are run:

test('planning with streams', (t, done) => {
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());
});

stream.on('end', () => {
done();
});
});

When using the wait option, you can control how long the test will wait for the expected assertions. For example, setting a maximum wait time ensures that the test will wait for asynchronous assertions to complete within the specified timeframe:

test('plan with wait: 2000 waits for async assertions', (t) => {
t.plan(1, { wait: 2000 }); // Waits for up to 2 seconds for the assertion to complete.

const asyncActivity = () => {
setTimeout(() => {
* t.assert.ok(true, 'Async assertion completed within the wait time');
}, 1000); // Completes after 1 second, within the 2-second wait time.
};

asyncActivity(); // The test will pass because the assertion is completed in time.
});

Note: If a wait timeout is specified, it begins counting down only after the test function finishes executing.