207 lines
6.1 KiB
Haxe
207 lines
6.1 KiB
Haxe
package node;
|
|
|
|
/**
|
|
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.
|
|
**/
|
|
@jsInaccessible extern class MockTimers {
|
|
function new();
|
|
/**
|
|
Enables timer mocking for the specified timers.
|
|
|
|
**Note:** When you enable mocking for a specific timer, its associated
|
|
clear function will also be implicitly mocked.
|
|
|
|
Example usage:
|
|
|
|
```js
|
|
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`,`node:timers/promises`, 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.
|
|
**/
|
|
function enable(?timers:Array<Timer>):Void;
|
|
/**
|
|
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`.
|
|
|
|
```js
|
|
import { mock } from 'node:test';
|
|
mock.timers.reset();
|
|
```
|
|
|
|
```js
|
|
const { mock } = require('node:test');
|
|
mock.timers.reset();
|
|
```
|
|
**/
|
|
function reset():Void;
|
|
/**
|
|
Advances time for all mocked 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.
|
|
|
|
```js
|
|
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
|
|
|
|
```js
|
|
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 = 9000;
|
|
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 = 9000;
|
|
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);
|
|
});
|
|
```
|
|
**/
|
|
function tick(milliseconds:Float):Void;
|
|
/**
|
|
Triggers all pending mocked timers immediately.
|
|
|
|
The example below triggers all pending timers immediately,
|
|
causing them to execute without any delay.
|
|
|
|
```js
|
|
import assert from 'node:assert';
|
|
import { test } from 'node:test';
|
|
|
|
test('runAll functions following the given order', (context) => {
|
|
context.mock.timers.enable(['setTimeout']);
|
|
const results = [];
|
|
setTimeout(() => results.push(1), 9999);
|
|
|
|
// Notice that if both timers have the same timeout,
|
|
// the order of execution is guaranteed
|
|
setTimeout(() => results.push(3), 8888);
|
|
setTimeout(() => results.push(2), 8888);
|
|
|
|
assert.deepStrictEqual(results, []);
|
|
|
|
context.mock.timers.runAll();
|
|
|
|
assert.deepStrictEqual(results, [3, 2, 1]);
|
|
});
|
|
```
|
|
|
|
```js
|
|
const assert = require('node:assert');
|
|
const { test } = require('node:test');
|
|
|
|
test('runAll functions following the given order', (context) => {
|
|
context.mock.timers.enable(['setTimeout']);
|
|
const results = [];
|
|
setTimeout(() => results.push(1), 9999);
|
|
|
|
// Notice that if both timers have the same timeout,
|
|
// the order of execution is guaranteed
|
|
setTimeout(() => results.push(3), 8888);
|
|
setTimeout(() => results.push(2), 8888);
|
|
|
|
assert.deepStrictEqual(results, []);
|
|
|
|
context.mock.timers.runAll();
|
|
|
|
assert.deepStrictEqual(results, [3, 2, 1]);
|
|
});
|
|
```
|
|
|
|
**Note:** The `runAll()` function is specifically designed for
|
|
triggering timers in the context of timer mocking.
|
|
It does not have any effect on real-time system
|
|
clocks or actual timers outside of the mocking environment.
|
|
**/
|
|
function runAll():Void;
|
|
static var prototype : MockTimers;
|
|
} |