1 | /**
|
2 | * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
|
3 | *
|
4 | * This source code is licensed under the MIT license found in the
|
5 | * LICENSE file in the root directory of this source tree.
|
6 | */
|
7 | /// <reference types="node" />
|
8 | import type { Context } from 'vm';
|
9 | import type { LegacyFakeTimers, ModernFakeTimers } from '@jest/fake-timers';
|
10 | import type { Circus, Config, Global } from '@jest/types';
|
11 | import type { fn as JestMockFn, spyOn as JestMockSpyOn, ModuleMocker } from 'jest-mock';
|
12 | export declare type EnvironmentContext = {
|
13 | console: Console;
|
14 | docblockPragmas: Record<string, string | Array<string>>;
|
15 | testPath: Config.Path;
|
16 | };
|
17 | export declare type ModuleWrapper = (this: Module['exports'], module: Module, exports: Module['exports'], require: Module['require'], __dirname: string, __filename: Module['filename'], jest?: Jest, ...extraGlobals: Array<Global.Global[keyof Global.Global]>) => unknown;
|
18 | export declare class JestEnvironment {
|
19 | constructor(config: Config.ProjectConfig, context?: EnvironmentContext);
|
20 | global: Global.Global;
|
21 | fakeTimers: LegacyFakeTimers<unknown> | null;
|
22 | fakeTimersModern: ModernFakeTimers | null;
|
23 | moduleMocker: ModuleMocker | null;
|
24 | getVmContext(): Context | null;
|
25 | setup(): Promise<void>;
|
26 | teardown(): Promise<void>;
|
27 | handleTestEvent?: Circus.EventHandler;
|
28 | }
|
29 | export declare type Module = NodeModule;
|
30 | export interface Jest {
|
31 | /**
|
32 | * Advances all timers by the needed milliseconds so that only the next timeouts/intervals will run.
|
33 | * Optionally, you can provide steps, so it will run steps amount of next timeouts/intervals.
|
34 | */
|
35 | advanceTimersToNextTimer(steps?: number): void;
|
36 | /**
|
37 | * Disables automatic mocking in the module loader.
|
38 | */
|
39 | autoMockOff(): Jest;
|
40 | /**
|
41 | * Enables automatic mocking in the module loader.
|
42 | */
|
43 | autoMockOn(): Jest;
|
44 | /**
|
45 | * Clears the mock.calls and mock.instances properties of all mocks.
|
46 | * Equivalent to calling .mockClear() on every mocked function.
|
47 | */
|
48 | clearAllMocks(): Jest;
|
49 | /**
|
50 | * Removes any pending timers from the timer system. If any timers have been
|
51 | * scheduled, they will be cleared and will never have the opportunity to
|
52 | * execute in the future.
|
53 | */
|
54 | clearAllTimers(): void;
|
55 | /**
|
56 | * Indicates that the module system should never return a mocked version
|
57 | * of the specified module, including all of the specified module's
|
58 | * dependencies.
|
59 | */
|
60 | deepUnmock(moduleName: string): Jest;
|
61 | /**
|
62 | * Disables automatic mocking in the module loader.
|
63 | *
|
64 | * After this method is called, all `require()`s will return the real
|
65 | * versions of each module (rather than a mocked version).
|
66 | */
|
67 | disableAutomock(): Jest;
|
68 | /**
|
69 | * When using `babel-jest`, calls to mock will automatically be hoisted to
|
70 | * the top of the code block. Use this method if you want to explicitly avoid
|
71 | * this behavior.
|
72 | */
|
73 | doMock(moduleName: string, moduleFactory?: () => unknown): Jest;
|
74 | /**
|
75 | * Indicates that the module system should never return a mocked version
|
76 | * of the specified module from require() (e.g. that it should always return
|
77 | * the real module).
|
78 | */
|
79 | dontMock(moduleName: string): Jest;
|
80 | /**
|
81 | * Enables automatic mocking in the module loader.
|
82 | */
|
83 | enableAutomock(): Jest;
|
84 | /**
|
85 | * Creates a mock function. Optionally takes a mock implementation.
|
86 | */
|
87 | fn: typeof JestMockFn;
|
88 | /**
|
89 | * Given the name of a module, use the automatic mocking system to generate a
|
90 | * mocked version of the module for you.
|
91 | *
|
92 | * This is useful when you want to create a manual mock that extends the
|
93 | * automatic mock's behavior.
|
94 | *
|
95 | * @deprecated Use `jest.createMockFromModule()` instead
|
96 | */
|
97 | genMockFromModule(moduleName: string): unknown;
|
98 | /**
|
99 | * Given the name of a module, use the automatic mocking system to generate a
|
100 | * mocked version of the module for you.
|
101 | *
|
102 | * This is useful when you want to create a manual mock that extends the
|
103 | * automatic mock's behavior.
|
104 | */
|
105 | createMockFromModule(moduleName: string): unknown;
|
106 | /**
|
107 | * Determines if the given function is a mocked function.
|
108 | */
|
109 | isMockFunction(fn: (...args: Array<any>) => unknown): fn is ReturnType<typeof JestMockFn>;
|
110 | /**
|
111 | * Mocks a module with an auto-mocked version when it is being required.
|
112 | */
|
113 | mock(moduleName: string, moduleFactory?: () => unknown, options?: {
|
114 | virtual?: boolean;
|
115 | }): Jest;
|
116 | /**
|
117 | * Returns the actual module instead of a mock, bypassing all checks on
|
118 | * whether the module should receive a mock implementation or not.
|
119 | *
|
120 | * @example
|
121 | ```
|
122 | jest.mock('../myModule', () => {
|
123 | // Require the original module to not be mocked...
|
124 | const originalModule = jest.requireActual(moduleName);
|
125 | return {
|
126 | __esModule: true, // Use it when dealing with esModules
|
127 | ...originalModule,
|
128 | getRandom: jest.fn().mockReturnValue(10),
|
129 | };
|
130 | });
|
131 |
|
132 | const getRandom = require('../myModule').getRandom;
|
133 |
|
134 | getRandom(); // Always returns 10
|
135 | ```
|
136 | */
|
137 | requireActual: (moduleName: string) => unknown;
|
138 | /**
|
139 | * Returns a mock module instead of the actual module, bypassing all checks
|
140 | * on whether the module should be required normally or not.
|
141 | */
|
142 | requireMock: (moduleName: string) => unknown;
|
143 | /**
|
144 | * Resets the state of all mocks.
|
145 | * Equivalent to calling .mockReset() on every mocked function.
|
146 | */
|
147 | resetAllMocks(): Jest;
|
148 | /**
|
149 | * Resets the module registry - the cache of all required modules. This is
|
150 | * useful to isolate modules where local state might conflict between tests.
|
151 | */
|
152 | resetModules(): Jest;
|
153 | /**
|
154 | * Restores all mocks back to their original value. Equivalent to calling
|
155 | * `.mockRestore` on every mocked function.
|
156 | *
|
157 | * Beware that jest.restoreAllMocks() only works when the mock was created with
|
158 | * jest.spyOn; other mocks will require you to manually restore them.
|
159 | */
|
160 | restoreAllMocks(): Jest;
|
161 | /**
|
162 | * Runs failed tests n-times until they pass or until the max number of
|
163 | * retries is exhausted. This only works with `jest-circus`!
|
164 | */
|
165 | retryTimes(numRetries: number): Jest;
|
166 | /**
|
167 | * Exhausts tasks queued by setImmediate().
|
168 | *
|
169 | * > Note: This function is not available when using Lolex as fake timers implementation
|
170 | */
|
171 | runAllImmediates(): void;
|
172 | /**
|
173 | * Exhausts the micro-task queue (usually interfaced in node via
|
174 | * process.nextTick).
|
175 | */
|
176 | runAllTicks(): void;
|
177 | /**
|
178 | * Exhausts the macro-task queue (i.e., all tasks queued by setTimeout()
|
179 | * and setInterval()).
|
180 | */
|
181 | runAllTimers(): void;
|
182 | /**
|
183 | * Executes only the macro-tasks that are currently pending (i.e., only the
|
184 | * tasks that have been queued by setTimeout() or setInterval() up to this
|
185 | * point). If any of the currently pending macro-tasks schedule new
|
186 | * macro-tasks, those new tasks will not be executed by this call.
|
187 | */
|
188 | runOnlyPendingTimers(): void;
|
189 | /**
|
190 | * Advances all timers by msToRun milliseconds. All pending "macro-tasks"
|
191 | * that have been queued via setTimeout() or setInterval(), and would be
|
192 | * executed within this timeframe will be executed.
|
193 | */
|
194 | advanceTimersByTime(msToRun: number): void;
|
195 | /**
|
196 | * Returns the number of fake timers still left to run.
|
197 | */
|
198 | getTimerCount(): number;
|
199 | /**
|
200 | * Explicitly supplies the mock object that the module system should return
|
201 | * for the specified module.
|
202 | *
|
203 | * Note It is recommended to use `jest.mock()` instead. The `jest.mock`
|
204 | * API's second argument is a module factory instead of the expected
|
205 | * exported module object.
|
206 | */
|
207 | setMock(moduleName: string, moduleExports: unknown): Jest;
|
208 | /**
|
209 | * Set the default timeout interval for tests and before/after hooks in
|
210 | * milliseconds.
|
211 | *
|
212 | * Note: The default timeout interval is 5 seconds if this method is not
|
213 | * called.
|
214 | */
|
215 | setTimeout(timeout: number): Jest;
|
216 | /**
|
217 | * Creates a mock function similar to `jest.fn` but also tracks calls to
|
218 | * `object[methodName]`.
|
219 | *
|
220 | * Note: By default, jest.spyOn also calls the spied method. This is
|
221 | * different behavior from most other test libraries.
|
222 | */
|
223 | spyOn: typeof JestMockSpyOn;
|
224 | /**
|
225 | * Indicates that the module system should never return a mocked version of
|
226 | * the specified module from require() (e.g. that it should always return the
|
227 | * real module).
|
228 | */
|
229 | unmock(moduleName: string): Jest;
|
230 | /**
|
231 | * Instructs Jest to use fake versions of the standard timer functions.
|
232 | */
|
233 | useFakeTimers(implementation?: 'modern' | 'legacy'): Jest;
|
234 | /**
|
235 | * Instructs Jest to use the real versions of the standard timer functions.
|
236 | */
|
237 | useRealTimers(): Jest;
|
238 | /**
|
239 | * `jest.isolateModules(fn)` goes a step further than `jest.resetModules()`
|
240 | * and creates a sandbox registry for the modules that are loaded inside
|
241 | * the callback function. This is useful to isolate specific modules for
|
242 | * every test so that local module state doesn't conflict between tests.
|
243 | */
|
244 | isolateModules(fn: () => void): Jest;
|
245 | /**
|
246 | * 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.
|
247 | *
|
248 | * > Note: This function is only available when using Lolex as fake timers implementation
|
249 | */
|
250 | getRealSystemTime(): number;
|
251 | /**
|
252 | * 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()`.
|
253 | *
|
254 | * > Note: This function is only available when using Lolex as fake timers implementation
|
255 | */
|
256 | setSystemTime(now?: number | Date): void;
|
257 | }
|