@jest/environment

constructor

constructor(config: JestEnvironmentConfig, context: EnvironmentContext);

property exportConditions

exportConditions?: () => Array<string>;

property fakeTimers

fakeTimers: any;

property fakeTimersModern

fakeTimersModern: any;

property global

global: Global.Global;

property handleTestEvent

handleTestEvent?: Circus.EventHandler;

property moduleMocker

moduleMocker: any;

method getVmContext

getVmContext: () => Context | null;

method setup

setup: () => Promise<void>;

method teardown

teardown: () => Promise<void>;

property fn

fn: ModuleMocker['fn'];

• Creates a mock function. Optionally takes a mock implementation.

property isMockFunction

isMockFunction: ModuleMocker['isMockFunction'];

• Determines if the given function is a mocked function.

property mocked

mocked: ModuleMocker['mocked'];

• Wraps types of the source object and its deep members with type definitions of Jest mock function. Pass {shallow: true} option to disable the deeply mocked behavior.

property replaceProperty

replaceProperty: ModuleMocker['replaceProperty'];

• Replaces property on an object with another value.

  Remarks

  For mocking functions or 'get' or 'set' accessors, use jest.spyOn() instead.

property spyOn

spyOn: ModuleMocker['spyOn'];

• Creates a mock function similar to jest.fn() but also tracks calls to object[methodName].

  Optional third argument of accessType can be either 'get' or 'set', which proves to be useful when you want to spy on a getter or a setter, respectively.

  Remarks

  By default, jest.spyOn() also calls the spied method. This is different behavior from most other test libraries.

method advanceTimersByTime

advanceTimersByTime: (msToRun: number) => void;

• Advances all timers by msToRun milliseconds. All pending "macro-tasks" that have been queued via setTimeout() or setInterval(), and would be executed within this time frame will be executed.

method advanceTimersByTimeAsync

advanceTimersByTimeAsync: (msToRun: number) => Promise<void>;

• Advances all timers by msToRun milliseconds, firing callbacks if necessary.

  Remarks

  Not available when using legacy fake timers implementation.

method advanceTimersToNextTimer

advanceTimersToNextTimer: (steps?: number) => void;

• Advances all timers by the needed milliseconds so that only the next timeouts/intervals will run. Optionally, you can provide steps, so it will run steps amount of next timeouts/intervals.

method advanceTimersToNextTimerAsync

advanceTimersToNextTimerAsync: (steps?: number) => Promise<void>;

• Advances the clock to the the moment of the first scheduled timer, firing it. Optionally, you can provide steps, so it will run steps amount of next timeouts/intervals.

  Remarks

  Not available when using legacy fake timers implementation.

method autoMockOff

autoMockOff: () => Jest;

• Disables automatic mocking in the module loader.

method autoMockOn

autoMockOn: () => Jest;

• Enables automatic mocking in the module loader.

method clearAllMocks

clearAllMocks: () => Jest;

• Clears the mock.calls, mock.instances, mock.contexts and mock.results properties of all mocks. Equivalent to calling .mockClear() on every mocked function.

method clearAllTimers

clearAllTimers: () => void;

• Removes any pending timers from the timer system. If any timers have been scheduled, they will be cleared and will never have the opportunity to execute in the future.

method createMockFromModule

createMockFromModule: <T = unknown>(moduleName: string) => Mocked<T>;

• Given the name of a module, use the automatic mocking system to generate a mocked version of the module for you.

  This is useful when you want to create a manual mock that extends the automatic mock's behavior.

method deepUnmock

deepUnmock: (moduleName: string) => Jest;

• Indicates that the module system should never return a mocked version of the specified module and its dependencies.

method disableAutomock

disableAutomock: () => Jest;

• Disables automatic mocking in the module loader.

  After this method is called, all require()s will return the real versions of each module (rather than a mocked version).

method doMock

doMock: <T = unknown>(
    moduleName: string,
    moduleFactory?: () => T,
    options?: { virtual?: boolean }
) => Jest;

• When using babel-jest, calls to jest.mock() will automatically be hoisted to the top of the code block. Use this method if you want to explicitly avoid this behavior.

method dontMock

dontMock: (moduleName: string) => Jest;

• When using babel-jest, calls to jest.unmock() will automatically be hoisted to the top of the code block. Use this method if you want to explicitly avoid this behavior.

method enableAutomock

enableAutomock: () => Jest;

• Enables automatic mocking in the module loader.

method genMockFromModule

genMockFromModule: <T = unknown>(moduleName: string) => Mocked<T>;

• Given the name of a module, use the automatic mocking system to generate a mocked version of the module for you.

  This is useful when you want to create a manual mock that extends the automatic mock's behavior.

  Deprecated

  Use jest.createMockFromModule() instead

method getRealSystemTime

getRealSystemTime: () => number;

• When mocking time, Date.now() will also be mocked. If you for some reason need access to the real current time, you can invoke this function.

  Remarks

  Not available when using legacy fake timers implementation.

method getSeed

getSeed: () => number;

• Retrieves the seed value. It will be randomly generated for each test run or can be manually set via the --seed CLI argument.

method getTimerCount

getTimerCount: () => number;

• Returns the number of fake timers still left to run.

method isEnvironmentTornDown

isEnvironmentTornDown: () => boolean;

• Returns true if test environment has been torn down.

  Example 1

  if (jest.isEnvironmentTornDown()) {
    // The Jest environment has been torn down, so stop doing work
    return;
  }

method isolateModules

isolateModules: (fn: () => void) => Jest;

• jest.isolateModules() goes a step further than jest.resetModules() and creates a sandbox registry for the modules that are loaded inside the callback function. This is useful to isolate specific modules for every test so that local module state doesn't conflict between tests.

method isolateModulesAsync

isolateModulesAsync: (fn: () => Promise<void>) => Promise<void>;

• jest.isolateModulesAsync() is the equivalent of jest.isolateModules(), but for async functions to be wrapped. The caller is expected to await the completion of isolateModulesAsync.

method mock

mock: <T = unknown>(
    moduleName: string,
    moduleFactory?: () => T,
    options?: { virtual?: boolean }
) => Jest;

• Mocks a module with an auto-mocked version when it is being required.

method now

now: () => number;

• Returns the current time in ms of the fake timer clock.

method requireActual

requireActual: <T = unknown>(moduleName: string) => T;

• Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not.

  Example 1

  jest.mock('../myModule', () => {
    // Require the original module to not be mocked...
    const originalModule = jest.requireActual('../myModule');
  
    return {
      __esModule: true, // Use it when dealing with esModules
      ...originalModule,
      getRandom: jest.fn().mockReturnValue(10),
    };
  });
  
  const getRandom = require('../myModule').getRandom;
  
  getRandom(); // Always returns 10

method requireMock

requireMock: <T = unknown>(moduleName: string) => T;

• Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not.

method resetAllMocks

resetAllMocks: () => Jest;

• Resets the state of all mocks. Equivalent to calling .mockReset() on every mocked function.

method resetModules

resetModules: () => Jest;

• Resets the module registry - the cache of all required modules. This is useful to isolate modules where local state might conflict between tests.

method restoreAllMocks

restoreAllMocks: () => Jest;

• Restores all mocks and replaced properties back to their original value. Equivalent to calling .mockRestore() on every mocked function and .restore() on every replaced property.

  Beware that jest.restoreAllMocks() only works when the mock was created with jest.spyOn(); other mocks will require you to manually restore them.

method retryTimes

retryTimes: (
    numRetries: number,
    options?: { logErrorsBeforeRetry?: boolean }
) => Jest;

• Runs failed tests n-times until they pass or until the max number of retries is exhausted.

  If logErrorsBeforeRetry is enabled, Jest will log the error(s) that caused the test to fail to the console, providing visibility on why a retry occurred. retries is exhausted.

  Remarks

  Only available with jest-circus runner.

method runAllImmediates

runAllImmediates: () => void;

• Exhausts tasks queued by setImmediate().

  Remarks

  Only available when using legacy fake timers implementation.

method runAllTicks

runAllTicks: () => void;

• Exhausts the micro-task queue (usually interfaced in node via process.nextTick()).

method runAllTimers

runAllTimers: () => void;

• Exhausts the macro-task queue (i.e., all tasks queued by setTimeout() and setInterval()).

method runAllTimersAsync

runAllTimersAsync: () => Promise<void>;

• Exhausts the macro-task queue (i.e., all tasks queued by setTimeout() and setInterval()).

  Remarks

  Not available when using legacy fake timers implementation.

method runOnlyPendingTimers

runOnlyPendingTimers: () => void;

• Executes only the macro-tasks that are currently pending (i.e., only the tasks that have been queued by setTimeout() or setInterval() up to this point). If any of the currently pending macro-tasks schedule new macro-tasks, those new tasks will not be executed by this call.

method runOnlyPendingTimersAsync

runOnlyPendingTimersAsync: () => Promise<void>;

• Executes only the macro-tasks that are currently pending (i.e., only the tasks that have been queued by setTimeout() or setInterval() up to this point). If any of the currently pending macro-tasks schedule new macro-tasks, those new tasks will not be executed by this call.

  Remarks

  Not available when using legacy fake timers implementation.

method setMock

setMock: (moduleName: string, moduleExports: unknown) => Jest;

• Explicitly supplies the mock object that the module system should return for the specified module.

  Remarks

  It is recommended to use jest.mock() instead. The jest.mock() API's second argument is a module factory instead of the expected exported module object.

method setSystemTime

setSystemTime: (now?: number | Date) => void;

• Set the current system time used by fake timers. Simulates a user changing the system clock while your program is running. It affects the current time, but it does not in itself cause e.g. timers to fire; they will fire exactly as they would have done without the call to jest.setSystemTime().

  Remarks

  Not available when using legacy fake timers implementation.

method setTimeout

setTimeout: (timeout: number) => Jest;

• Set the default timeout interval for tests and before/after hooks in milliseconds.

  Remarks

  The default timeout interval is 5 seconds if this method is not called.

method unmock

unmock: (moduleName: string) => Jest;

• Indicates that the module system should never return a mocked version of the specified module from require() (e.g. that it should always return the real module).

method unstable_mockModule

unstable_mockModule: <T = unknown>(
    moduleName: string,
    moduleFactory: () => T | Promise<T>,
    options?: { virtual?: boolean }
) => Jest;

• Mocks a module with the provided module factory when it is being imported.

method useFakeTimers

useFakeTimers: (
    fakeTimersConfig?: Config.FakeTimersConfig | Config.LegacyFakeTimersConfig
) => Jest;

• Instructs Jest to use fake versions of the global date, performance, time and timer APIs. Fake timers implementation is backed by [@sinonjs/fake-timers](https://github.com/sinonjs/fake-timers).

  Remarks

  Calling jest.useFakeTimers() once again in the same test file would reinstall fake timers using the provided options.

method useRealTimers

useRealTimers: () => Jest;

• Instructs Jest to restore the original implementations of the global date, performance, time and timer APIs.

property globalConfig

globalConfig: Config.GlobalConfig;

property projectConfig

projectConfig: Config.ProjectConfig;

property jest

jest: Jest;