test.default.MockTracker

interface MockTracker

• readonly timers: MockTimers
• fn<F extends Function = (...args: any[]) => undefined>(

  original?: F,

  options?: MockFunctionOptions

  ): Mock<F>;

  This function is used to create a mock function.

  The following example creates a mock function that increments a counter by one on each invocation. The times option is used to modify the mock behavior such that the first two invocations add two to the counter instead of one.

  test('mocks a counting function', (t) => {
    let cnt = 0;
  
    function addOne() {
      cnt++;
      return cnt;
    }
  
    function addTwo() {
      cnt += 2;
      return cnt;
    }
  
    const fn = t.mock.fn(addOne, addTwo, { times: 2 });
  
    assert.strictEqual(fn(), 2);
    assert.strictEqual(fn(), 4);
    assert.strictEqual(fn(), 5);
    assert.strictEqual(fn(), 6);
  });
  

  @param original

  An optional function to create a mock on.

  @param options

  Optional configuration options for the mock function.

  @returns

  The mocked function. The mocked function contains a special mock property, which is an instance of MockFunctionContext, and can be used for inspecting and changing the behavior of the mocked function.

  fn<F extends Function = (...args: any[]) => undefined, Implementation extends Function = F>(

  original?: F,

  implementation?: Implementation,

  options?: MockFunctionOptions

  ): Mock<F | Implementation>;
• getter<MockedObject extends object, MethodName extends string | number | symbol>(

  object: MockedObject,

  methodName: MethodName,

  options?: MockFunctionOptions

  ): Mock<() => MockedObject[MethodName]>;

  This function is syntax sugar for MockTracker.method with options.getter set to true.

  getter<MockedObject extends object, MethodName extends string | number | symbol, Implementation extends Function>(

  object: MockedObject,

  methodName: MethodName,

  implementation?: Implementation,

  options?: MockFunctionOptions

  ): Mock<Implementation | () => MockedObject[MethodName]>;
• method<MockedObject extends object, MethodName extends string | number | symbol>(

  object: MockedObject,

  methodName: MethodName,

  options?: MockFunctionOptions

  ): MockedObject[MethodName] extends Function ? Mock<any[any]> : never;

  This function is used to create a mock on an existing object method. The following example demonstrates how a mock is created on an existing object method.

  test('spies on an object method', (t) => {
    const number = {
      value: 5,
      subtract(a) {
        return this.value - a;
      },
    };
  
    t.mock.method(number, 'subtract');
    assert.strictEqual(number.subtract.mock.calls.length, 0);
    assert.strictEqual(number.subtract(3), 2);
    assert.strictEqual(number.subtract.mock.calls.length, 1);
  
    const call = number.subtract.mock.calls[0];
  
    assert.deepStrictEqual(call.arguments, [3]);
    assert.strictEqual(call.result, 2);
    assert.strictEqual(call.error, undefined);
    assert.strictEqual(call.target, undefined);
    assert.strictEqual(call.this, number);
  });
  

  @param object

  The object whose method is being mocked.

  @param methodName

  The identifier of the method on object to mock. If object[methodName] is not a function, an error is thrown.

  @param options

  Optional configuration options for the mock method.

  @returns

  The mocked method. The mocked method contains a special mock property, which is an instance of MockFunctionContext, and can be used for inspecting and changing the behavior of the mocked method.

  method<MockedObject extends object, MethodName extends string | number | symbol, Implementation extends Function>(

  object: MockedObject,

  methodName: MethodName,

  implementation: Implementation,

  options?: MockFunctionOptions

  ): MockedObject[MethodName] extends Function ? Mock<Implementation | any[any]> : never;

  method<MockedObject extends object>(

  object: MockedObject,

  methodName: keyof MockedObject,

  options: MockMethodOptions

  ): Mock<Function>;

  method<MockedObject extends object>(

  object: MockedObject,

  methodName: keyof MockedObject,

  implementation: Function,

  options: MockMethodOptions

  ): Mock<Function>;
• module(

  specifier: string,

  options?: MockModuleOptions

  ): MockModuleContext;

  This function is used to mock the exports of ECMAScript modules, CommonJS modules, JSON modules, and Node.js builtin modules. Any references to the original module prior to mocking are not impacted. In order to enable module mocking, Node.js must be started with the --experimental-test-module-mocks command-line flag.

  The following example demonstrates how a mock is created for a module.

  test('mocks a builtin module in both module systems', async (t) => {
    // Create a mock of 'node:readline' with a named export named 'fn', which
    // does not exist in the original 'node:readline' module.
    const mock = t.mock.module('node:readline', {
      namedExports: { fn() { return 42; } },
    });
  
    let esmImpl = await import('node:readline');
    let cjsImpl = require('node:readline');
  
    // cursorTo() is an export of the original 'node:readline' module.
    assert.strictEqual(esmImpl.cursorTo, undefined);
    assert.strictEqual(cjsImpl.cursorTo, undefined);
    assert.strictEqual(esmImpl.fn(), 42);
    assert.strictEqual(cjsImpl.fn(), 42);
  
    mock.restore();
  
    // The mock is restored, so the original builtin module is returned.
    esmImpl = await import('node:readline');
    cjsImpl = require('node:readline');
  
    assert.strictEqual(typeof esmImpl.cursorTo, 'function');
    assert.strictEqual(typeof cjsImpl.cursorTo, 'function');
    assert.strictEqual(esmImpl.fn, undefined);
    assert.strictEqual(cjsImpl.fn, undefined);
  });
  

  @param specifier

  A string identifying the module to mock.

  @param options

  Optional configuration options for the mock module.

• property<MockedObject extends object, PropertyName extends string | number | symbol>(

  object: MockedObject,

  property: PropertyName,

  value?: MockedObject[PropertyName]

  ): MockedObject & { mock: MockPropertyContext<MockedObject[PropertyName]> };

  Creates a mock for a property value on an object. This allows you to track and control access to a specific property, including how many times it is read (getter) or written (setter), and to restore the original value after mocking.

  test('mocks a property value', (t) => {
    const obj = { foo: 42 };
    const prop = t.mock.property(obj, 'foo', 100);
  
    assert.strictEqual(obj.foo, 100);
    assert.strictEqual(prop.mock.accessCount(), 1);
    assert.strictEqual(prop.mock.accesses[0].type, 'get');
    assert.strictEqual(prop.mock.accesses[0].value, 100);
  
    obj.foo = 200;
    assert.strictEqual(prop.mock.accessCount(), 2);
    assert.strictEqual(prop.mock.accesses[1].type, 'set');
    assert.strictEqual(prop.mock.accesses[1].value, 200);
  
    prop.mock.restore();
    assert.strictEqual(obj.foo, 42);
  });
  

  @param object

  The object whose value is being mocked.

  @param value

  An optional value used as the mock value for object[propertyName]. Default: The original property value.

  @returns

  A proxy to the mocked object. The mocked object contains a special mock property, which is an instance of [MockPropertyContext][], and can be used for inspecting and changing the behavior of the mocked property.

• reset(): void;

  This function restores the default behavior of all mocks that were previously created by this MockTracker and disassociates the mocks from the MockTracker instance. Once disassociated, the mocks can still be used, but the MockTracker instance can no longer be used to reset their behavior or otherwise interact with them.

  After each test completes, this function is called on the test context's MockTracker. If the global MockTracker is used extensively, calling this function manually is recommended.

• restoreAll(): void;

  This function restores the default behavior of all mocks that were previously created by this MockTracker. Unlike mock.reset(), mock.restoreAll() does not disassociate the mocks from the MockTracker instance.

• setter<MockedObject extends object, MethodName extends string | number | symbol>(

  object: MockedObject,

  methodName: MethodName,

  options?: MockFunctionOptions

  ): Mock<(value: MockedObject[MethodName]) => void>;

  This function is syntax sugar for MockTracker.method with options.setter set to true.

  setter<MockedObject extends object, MethodName extends string | number | symbol, Implementation extends Function>(

  object: MockedObject,

  methodName: MethodName,

  implementation?: Implementation,

  options?: MockFunctionOptions

  ): Mock<Implementation | (value: MockedObject[MethodName]) => void>;