@jest/environment

  • Version 29.7.0
  • Published
  • 15.9 kB
  • 4 dependencies
  • MIT license

Install

npm i @jest/environment
yarn add @jest/environment
pnpm add @jest/environment

Overview

Overview not available.

Index

Classes

class JestEnvironment

class JestEnvironment<Timer = unknown> {}

    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>;

                        Interfaces

                        interface Jest

                        interface Jest {}

                          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.

                          interface JestEnvironmentConfig

                          interface JestEnvironmentConfig {}

                            property globalConfig

                            globalConfig: Config.GlobalConfig;

                              property projectConfig

                              projectConfig: Config.ProjectConfig;

                                interface JestImportMeta

                                interface JestImportMeta extends ImportMeta {}

                                  property jest

                                  jest: Jest;

                                    Type Aliases

                                    type EnvironmentContext

                                    type EnvironmentContext = {
                                    console: Console;
                                    docblockPragmas: Record<string, string | Array<string>>;
                                    testPath: string;
                                    };

                                      type Module

                                      type Module = NodeModule;

                                        type ModuleWrapper

                                        type ModuleWrapper = (
                                        this: Module['exports'],
                                        module: Module,
                                        exports: Module['exports'],
                                        require: Module['require'],
                                        __dirname: string,
                                        __filename: Module['filename'],
                                        jest?: Jest,
                                        ...sandboxInjectedGlobals: Array<Global.Global[keyof Global.Global]>
                                        ) => unknown;

                                          Package Files (1)

                                          Dependencies (4)

                                          Dev Dependencies (0)

                                          No dev dependencies.

                                          Peer Dependencies (0)

                                          No peer dependencies.

                                          Badge

                                          To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                          You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@jest/environment.

                                          • Markdown
                                            [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@jest/environment)
                                          • HTML
                                            <a href="https://www.jsdocs.io/package/@jest/environment"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>