-
-
Notifications
You must be signed in to change notification settings - Fork 6.5k
/
index.ts
291 lines (281 loc) · 9.89 KB
/
index.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
/**
* Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import type {Context} from 'vm';
import type {LegacyFakeTimers, ModernFakeTimers} from '@jest/fake-timers';
import type {Circus, Config, Global} from '@jest/types';
import type {ModuleMocker} from 'jest-mock';
export type EnvironmentContext = {
console: Console;
docblockPragmas: Record<string, string | Array<string>>;
testPath: string;
};
// Different Order than https://nodejs.org/api/modules.html#modules_the_module_wrapper , however needs to be in the form [jest-transform]ScriptTransformer accepts
export 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;
export declare class JestEnvironment<Timer = unknown> {
constructor(config: Config.ProjectConfig, context?: EnvironmentContext);
global: Global.Global;
fakeTimers: LegacyFakeTimers<Timer> | null;
fakeTimersModern: ModernFakeTimers | null;
moduleMocker: ModuleMocker | null;
getVmContext(): Context | null;
setup(): Promise<void>;
teardown(): Promise<void>;
handleTestEvent?: Circus.EventHandler;
exportConditions?: () => Array<string>;
}
export type Module = NodeModule;
// TODO: Move to some separate package
export interface Jest {
/**
* 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.
*/
advanceTimersToNextTimer(steps?: number): void;
/**
* Disables automatic mocking in the module loader.
*/
autoMockOff(): Jest;
/**
* Enables automatic mocking in the module loader.
*/
autoMockOn(): Jest;
/**
* Clears the mock.calls and mock.instances properties of all mocks.
* Equivalent to calling .mockClear() on every mocked function.
*/
clearAllMocks(): Jest;
/**
* 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.
*/
clearAllTimers(): void;
/**
* Indicates that the module system should never return a mocked version
* of the specified module, including all of the specified module's
* dependencies.
*/
deepUnmock(moduleName: string): 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).
*/
disableAutomock(): Jest;
/**
* When using `babel-jest`, calls to mock will automatically be hoisted to
* the top of the code block. Use this method if you want to explicitly avoid
* this behavior.
*/
doMock(
moduleName: string,
moduleFactory?: () => unknown,
options?: {virtual?: boolean},
): 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).
*/
dontMock(moduleName: string): Jest;
/**
* Enables automatic mocking in the module loader.
*/
enableAutomock(): Jest;
/**
* Creates a mock function. Optionally takes a mock implementation.
*/
fn: ModuleMocker['fn'];
/**
* 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
*/
genMockFromModule(moduleName: string): unknown;
/**
* 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.
*/
createMockFromModule(moduleName: string): unknown;
/**
* Determines if the given function is a mocked function.
*/
isMockFunction: ModuleMocker['isMockFunction'];
/**
* Mocks a module with an auto-mocked version when it is being required.
*/
mock(
moduleName: string,
moduleFactory?: () => unknown,
options?: {virtual?: boolean},
): Jest;
/**
* Mocks a module with the provided module factory when it is being imported.
*/
unstable_mockModule<T = unknown>(
moduleName: string,
moduleFactory: () => Promise<T> | T,
options?: {virtual?: boolean},
): Jest;
/**
* Returns the actual module instead of a mock, bypassing all checks on
* whether the module should receive a mock implementation or not.
*
* @example
```
jest.mock('../myModule', () => {
// Require the original module to not be mocked...
const originalModule = jest.requireActual(moduleName);
return {
__esModule: true, // Use it when dealing with esModules
...originalModule,
getRandom: jest.fn().mockReturnValue(10),
};
});
const getRandom = require('../myModule').getRandom;
getRandom(); // Always returns 10
```
*/
requireActual: (moduleName: string) => unknown;
/**
* Returns a mock module instead of the actual module, bypassing all checks
* on whether the module should be required normally or not.
*/
requireMock: (moduleName: string) => unknown;
/**
* Resets the state of all mocks.
* Equivalent to calling .mockReset() on every mocked function.
*/
resetAllMocks(): Jest;
/**
* Resets the module registry - the cache of all required modules. This is
* useful to isolate modules where local state might conflict between tests.
*/
resetModules(): Jest;
/**
* Restores all mocks back to their original value. Equivalent to calling
* `.mockRestore` on every mocked function.
*
* Beware that jest.restoreAllMocks() only works when the mock was created with
* jest.spyOn; other mocks will require you to manually restore them.
*/
restoreAllMocks(): Jest;
mocked: ModuleMocker['mocked'];
/**
* Runs failed tests n-times until they pass or until the max number of
* retries is exhausted. This only works with `jest-circus`!
*/
retryTimes(numRetries: number): Jest;
/**
* Exhausts tasks queued by setImmediate().
*
* > Note: This function is not available when using Lolex as fake timers implementation
*/
runAllImmediates(): void;
/**
* Exhausts the micro-task queue (usually interfaced in node via
* process.nextTick).
*/
runAllTicks(): void;
/**
* Exhausts the macro-task queue (i.e., all tasks queued by setTimeout()
* and setInterval()).
*/
runAllTimers(): 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.
*/
runOnlyPendingTimers(): 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 timeframe will be executed.
*/
advanceTimersByTime(msToRun: number): void;
/**
* Returns the number of fake timers still left to run.
*/
getTimerCount(): number;
/**
* Explicitly supplies the mock object that the module system should return
* for the specified module.
*
* Note 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.
*/
setMock(moduleName: string, moduleExports: unknown): Jest;
/**
* Set the default timeout interval for tests and before/after hooks in
* milliseconds.
*
* Note: The default timeout interval is 5 seconds if this method is not
* called.
*/
setTimeout(timeout: number): Jest;
/**
* Creates a mock function similar to `jest.fn` but also tracks calls to
* `object[methodName]`.
*
* Note: By default, jest.spyOn also calls the spied method. This is
* different behavior from most other test libraries.
*/
spyOn: ModuleMocker['spyOn'];
/**
* 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).
*/
unmock(moduleName: string): Jest;
/**
* Instructs Jest to use fake versions of the standard timer functions.
*/
useFakeTimers(implementation?: 'modern' | 'legacy'): Jest;
/**
* Instructs Jest to use the real versions of the standard timer functions.
*/
useRealTimers(): Jest;
/**
* `jest.isolateModules(fn)` 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.
*/
isolateModules(fn: () => void): Jest;
/**
* 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.
*
* > Note: This function is only available when using Lolex as fake timers implementation
*/
getRealSystemTime(): number;
/**
* 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()`.
*
* > Note: This function is only available when using Lolex as fake timers implementation
*/
setSystemTime(now?: number | Date): void;
}