test_runner: add docs for timers.tick

Signed-off-by: Erick Wendel <[email protected]>
nodejs · nodejs-github-bot · Jun 22, 2023 · Apr 28, 2023 · May 1, 2023 · May 1, 2023
commit 13fab2bb1030b043db91a8516716d6c0d48f7bc5
diff --git a/doc/api/test.md b/doc/api/test.md
@@ -1506,6 1506,345 @@ added:
 
 > Stability: 1 - Experimental
 
 Mocking timers is a technique commonly used in software testing to simulate and
 control the behavior of timers, such as `setInterval` and `setTimeout`,
 without actually waiting for the specified time intervals.
 
 The [`MockTracker`][] provides a top level `timers` export
 which is a MockTimers instance
 
 ### `timers.enable([,timers])`
 <!-- YAML
 added:
  - REPLACEME
 -->
 
 Enables timer mocking for the specified timers.
 
 * `timers` {Array} An optional array containing the timers to mock.
 The currently supported timer values are `'setInterval'` and `'setTimeout'`.
 If no array is provided, all timers (`'setInterval'`, `'clearInterval'`, `'setTimeout'`,
 and `'clearTimeout'`) will be mocked by default.
 
 **Note:** When you enable mocking for a specific timer, its associated
 clear function will also be implicitly mocked.
 
 Example usage:
 
 ```mjs
 import { mock } from 'node:test';
 mock.timers.enable(['setInterval']);
 ```
 ```js
 const { mock } = require('node:test');
 mock.timers.enable(['setInterval']);
 ```
 
 The above example enables mocking for the `setInterval` timer and
 implicitly mocks the `clearInterval` function. Only the `setInterval`
  and `clearInterval` functions from [node:timers](./timers.md),
 [node:timers/promises](./timers.md#timers-promises-api), and
 `globalThis` will be mocked.
 
 Alternatively, if you call `mock.timers.enable()` without any parameters:
 
 All timers (`'setInterval'`, `'clearInterval'`, `'setTimeout'`, and `'clearTimeout'`)
 will be mocked. The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout`
 functions from `node:timers`, `node:timers/promises`,
 and `globalThis` will be mocked.
 
 ### `timers.reset()`
 <!-- YAML
 added:
  - REPLACEME
 -->
 
 This function restores the default behavior of all mocks that were previously
 created by this `MockTimers` instance and disassociates the mocks
 from the `MockTracker` instance.
 
 **Note:** After each test completes, this function is called on
 the test context's `MockTracker`.
 
 ```mjs
 import { mock } from 'node:test';
 mock.timers.reset();
 ```
 ```js
 const { mock } = require('node:test');
 mock.timers.reset();
 ```
 
 ### `timers.tick(milliseconds)`
 <!-- YAML
 added:
  - REPLACEME
 -->
 Advances time for all mocked timers.
 
 * `milliseconds` {number} The amount of time, in milliseconds,
 to advance the timers.
 
 **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts
 only positive numbers. In Node.js, `setTimeout` with negative numbers is
 only supported for web compatibility reasons.
 
 The following example mocks a `setTimeout` function and
 by using `.tick` advances in
 time triggering all pending timers.
 
 ```mjs
 import assert from 'node:assert';
 import { test } from 'node:test';
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
 
  context.mock.timers.enable(['setTimeout']);
 
  setTimeout(fn, 9999);
 
  assert.strictEqual(fn.mock.callCount(), 0);
 
  // Advance in time
  context.mock.timers.tick(9999);
 
  assert.strictEqual(fn.mock.callCount(), 1);
 });
 ```
 ```js
 const assert = require('node:assert');
 const { test } = require('node:test');
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
  context.mock.timers.enable(['setTimeout']);
 
  setTimeout(fn, 9999);
  assert.strictEqual(fn.mock.callCount(), 0);
 
  // Advance in time
  context.mock.timers.tick(9999);
 
  assert.strictEqual(fn.mock.callCount(), 1);
 });
 ```
 Alternativelly, the `.tick` function can be called many times
 
 ```mjs
 import assert from 'node:assert';
 import { test } from 'node:test';
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
  context.mock.timers.enable(['setTimeout']);
  const nineSecs = 9500;
  setTimeout(fn, nineSecs);
 
  const twoSeconds = 3000;
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);
 
  assert.strictEqual(fn.mock.callCount(), 1);
 });
 ```
 
 ```js
 const assert = require('node:assert');
 const { test } = require('node:test');
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
  context.mock.timers.enable(['setTimeout']);
  const nineSecs = 9500;
  setTimeout(fn, nineSecs);
 
  const twoSeconds = 3000;
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);
 
  assert.strictEqual(fn.mock.callCount(), 1);
 });
 ```
 
 #### Using Clear functions
 
 As mentioned, all clear functions from timers (clearTimeout and clearInterval)
 are implicity mocked.Take a look at this example using `setTimeout`:
 
 ```mjs
 import assert from 'node:assert';
 import { test } from 'node:test';
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
 
  // Optionally choose what to mock
  context.mock.timers.enable(['setTimeout']);
  const id = setTimeout(fn, 9999);
 
  // Implicity mocked as well
  clearTimeout(id);
  context.mock.timers.tick(9999);
 
  // As that setTimeout was cleared the mock function will never be called
  assert.strictEqual(fn.mock.callCount(), 0);
 });
 ```
 
 ```js
 const assert = require('node:assert');
 const { test } = require('node:test');
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
 
  // Optionally choose what to mock
  context.mock.timers.enable(['setTimeout']);
  const id = setTimeout(fn, 9999);
 
  // Implicity mocked as well
  clearTimeout(id);
  context.mock.timers.tick(9999);
 
  // As that setTimeout was cleared the mock function will never be called
  assert.strictEqual(fn.mock.callCount(), 0);
 });
 ```
 #### Working with Node.js timers modules
 
 Once you enable mocking timers, [node:timers](./timers.md),
 [node:timers/promises](./timers.md#timers-promises-api) modules,
 and timers from the Node.js global context are enabled:
 
 ```mjs
 import assert from 'node:assert';
 import { test } from 'node:test';
 import nodeTimers from 'node:timers';
 import nodeTimersPromises from 'node:timers/promises';
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', async (context) => {
  const globalTimeoutObjectSpy = context.mock.fn();
  const nodeTimerSpy = context.mock.fn();
  const nodeTimerPromiseSpy = context.mock.fn();
 
  // Optionally choose what to mock
  context.mock.timers.enable(['setTimeout']);
  setTimeout(globalTimeoutObjectSpy, 9999);
  nodeTimers.setTimeout(nodeTimerSpy, 9999);
 
  const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy);
 
  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1);
  assert.strictEqual(nodeTimerSpy.mock.callCount(), 1);
  await promise;
  assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1);
 });
 ```
 ```js
 const assert = require('node:assert');
 const { test } = require('node:test');
 const nodeTimers = require('node:timers');
 const nodeTimersPromises = require('node:timers/promises');
 
 test('mocks setTimeout to be executed synchronously without having to actually wait for it', async (context) => {
  const globalTimeoutObjectSpy = context.mock.fn();
  const nodeTimerSpy = context.mock.fn();
  const nodeTimerPromiseSpy = context.mock.fn();
 
  // Optionally choose what to mock
  context.mock.timers.enable(['setTimeout']);
  setTimeout(globalTimeoutObjectSpy, 9999);
  nodeTimers.setTimeout(nodeTimerSpy, 9999);
 
  const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy);
 
  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1);
  assert.strictEqual(nodeTimerSpy.mock.callCount(), 1);
  await promise;
  assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1);
 });
 ```
 In Node.js, `setInterval` from [node:timers/promises](./timers.md#timers-promises-api)
  is a Async Gerator and is also supported by this API:
 
 ```mjs
 import assert from 'node:assert';
 import { test } from 'node:test';
 import nodeTimersPromises from 'node:timers/promises';
 test('should tick five times testing a real use case', async (context) => {
 
  context.mock.timers.enable(['setInterval']);
 
  const expectedIterations = 3;
  const interval = 1000;
  const startedAt = Date.now();
  async function run() {
  const times = [];
  for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
  times.push(time);
  if (times.length === expectedIterations) break;
  }
  return times;
  }
 
  const r = run();
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);
 
  const timeResults = await r;
  assert.strictEqual(timeResults.length, expectedIterations);
  for (let it = 1; it < expectedIterations; it ) {
  assert.strictEqual(timeResults[it - 1], startedAt (interval * it));
  }
 });
 ```
 ```js
 const assert = require('node:assert');
 const { test } = require('node:test');
 const nodeTimersPromises = require('node:timers/promises');
 test('should tick five times testing a real use case', async (context) => {
 
  context.mock.timers.enable(['setInterval']);
 
  const expectedIterations = 3;
  const interval = 1000;
  const startedAt = Date.now();
  async function run() {
  const times = [];
  for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
  times.push(time);
  if (times.length === expectedIterations) break;
  }
  return times;
  }
 
  const r = run();
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);
 
  const timeResults = await r;
  assert.strictEqual(timeResults.length, expectedIterations);
  for (let it = 1; it < expectedIterations; it ) {
  assert.strictEqual(timeResults[it - 1], startedAt (interval * it));
  }
 });
 ```
 
 ### `timers.runAll()`
 <!-- YAML
 added:
  - REPLACEME
 -->
 
 ## Class: `TestsStream`
 
 <!-- YAML