0
# Global Test Framework Types
1

2
Core types for Jest's global test framework functions, hooks, and test organization. These types enable type-safe test writing and custom test utility development.
3

4
## Capabilities
5

6
### Test Function Types
7

8
Core test function signatures and return value types.
9

10
```typescript { .api }
11
/**
12
 * Valid return values for test functions
13
 */
14
type ValidTestReturnValues = void | undefined;
15

16
/**
17
 * Promise-based test return value
18
 */
19
type TestReturnValue = ValidTestReturnValues | Promise<unknown>;
20

21
/**
22
 * Test execution context object
23
 */
24
type TestContext = Record<string, unknown>;
25

26
/**
27
 * Done callback function for async tests
28
 */
29
type DoneFn = (reason?: string | Error) => void;
30

31
/**
32
 * Test function that uses done callback
33
 */
34
type DoneTakingTestFn = (this: TestContext, done: DoneFn) => ValidTestReturnValues;
35

36
/**
37
 * Test function that returns a promise
38
 */
39
type PromiseReturningTestFn = (this: TestContext) => TestReturnValue;
40

41
/**
42
 * Test function that returns a generator
43
 */
44
type GeneratorReturningTestFn = (this: TestContext) => Generator<void, unknown, void>;
45

46
/**
47
 * Union of all test function types
48
 */
49
type TestFn = PromiseReturningTestFn | GeneratorReturningTestFn | DoneTakingTestFn;
50

51
/**
52
 * Concurrent test function (must return Promise)
53
 */
54
type ConcurrentTestFn = () => Promise<unknown>;
55

56
/**
57
 * Hook function (same as TestFn)
58
 */
59
type HookFn = TestFn;
60
```
61

62
### Test and Block Naming Types
63

64
Types for test and describe block names and identifiers.
65

66
```typescript { .api }
67
/**
68
 * Name-like values that can be used as test/block names
69
 */
70
type NameLike = number | Function;
71

72
/**
73
 * Test name (string)
74
 */
75
type TestName = string;
76

77
/**
78
 * Test name or name-like value
79
 */
80
type TestNameLike = TestName | NameLike;
81

82
/**
83
 * Block function for describe blocks
84
 */
85
type BlockFn = () => void;
86

87
/**
88
 * Block name (string)
89
 */
90
type BlockName = string;
91

92
/**
93
 * Block name or name-like value
94
 */
95
type BlockNameLike = BlockName | NameLike;
96
```
97

98
### Parameterized Testing Types
99

100
Types for Jest's parameterized testing (test.each, describe.each) functionality.
101

102
```typescript { .api }
103
/**
104
 * Column value in test data table
105
 */
106
type Col = unknown;
107

108
/**
109
 * Row of test data
110
 */
111
type Row = ReadonlyArray<Col>;
112

113
/**
114
 * Table of test data rows
115
 */
116
type Table = ReadonlyArray<Row>;
117

118
/**
119
 * Array-based table data
120
 */
121
type ArrayTable = Table | Row;
122

123
/**
124
 * Template string table
125
 */
126
type TemplateTable = TemplateStringsArray;
127

128
/**
129
 * Template data array
130
 */
131
type TemplateData = ReadonlyArray<unknown>;
132

133
/**
134
 * Either array or template table format
135
 */
136
type EachTable = ArrayTable | TemplateTable;
137

138
/**
139
 * Test callback function for parameterized tests
140
 */
141
type TestCallback = BlockFn | TestFn | ConcurrentTestFn;
142

143
/**
144
 * Each test function with parameters
145
 */
146
type EachTestFn<EachCallback extends TestCallback> = (
147
  ...args: ReadonlyArray<any>
148
) => ReturnType<EachCallback>;
149
```
150

151
### Each Interface
152

153
Generic interface for parameterized test functions with multiple overload signatures.
154

155
```typescript { .api }
156
interface Each<EachFn extends TestFn | BlockFn> {
157
  // Array of object literals table
158
  <T extends Record<string, unknown>>(
159
    table: ReadonlyArray<T>
160
  ): (
161
    name: string | NameLike,
162
    fn: (arg: T, done: DoneFn) => ReturnType<EachFn>,
163
    timeout?: number
164
  ) => void;
165

166
  // Array of tuples table
167
  <T extends readonly [unknown, ...Array<unknown>]>(
168
    table: ReadonlyArray<T>
169
  ): (
170
    name: string | NameLike,
171
    fn: (...args: [...T]) => ReturnType<EachFn>,
172
    timeout?: number
173
  ) => void;
174

175
  // Array of arrays table
176
  <T extends ReadonlyArray<unknown>>(
177
    table: ReadonlyArray<T>
178
  ): (
179
    name: string | NameLike,
180
    fn: (...args: T) => ReturnType<EachFn>,
181
    timeout?: number
182
  ) => void;
183

184
  // Generic array table
185
  <T>(
186
    table: ReadonlyArray<T>
187
  ): (
188
    name: string | NameLike,
189
    fn: (arg: T, done: DoneFn) => ReturnType<EachFn>,
190
    timeout?: number
191
  ) => void;
192

193
  // Template literal table
194
  <T extends Array<unknown>>(
195
    strings: TemplateStringsArray,
196
    ...expressions: T
197
  ): (
198
    name: string | NameLike,
199
    fn: (arg: Record<string, T[number]>, done: DoneFn) => ReturnType<EachFn>,
200
    timeout?: number
201
  ) => void;
202

203
  // Template literal with type argument
204
  <T extends Record<string, unknown>>(
205
    strings: TemplateStringsArray,
206
    ...expressions: Array<unknown>
207
  ): (
208
    name: string | NameLike,
209
    fn: (arg: T, done: DoneFn) => ReturnType<EachFn>,
210
    timeout?: number
211
  ) => void;
212
}
213
```
214

215
### Hook and Test Interface Types
216

217
Interface types for Jest's test and hook functions.
218

219
```typescript { .api }
220
/**
221
 * Base hook function signature
222
 */
223
type HookBase = (fn: HookFn, timeout?: number) => void;
224

225
/**
226
 * Failing test interface
227
 */
228
interface Failing<T extends TestFn> {
229
  (testName: TestNameLike, fn: T, timeout?: number): void;
230
  each: Each<T>;
231
}
232

233
/**
234
 * Base it/test interface
235
 */
236
interface ItBase {
237
  (testName: TestNameLike, fn: TestFn, timeout?: number): void;
238
  each: Each<TestFn>;
239
  failing: Failing<TestFn>;
240
}
241

242
/**
243
 * Extended it/test interface with modifiers
244
 */
245
interface It extends ItBase {
246
  only: ItBase;
247
  skip: ItBase;
248
  todo: (testName: TestNameLike) => void;
249
}
250

251
/**
252
 * Base concurrent test interface
253
 */
254
interface ItConcurrentBase {
255
  (testName: TestNameLike, testFn: ConcurrentTestFn, timeout?: number): void;
256
  each: Each<ConcurrentTestFn>;
257
  failing: Failing<ConcurrentTestFn>;
258
}
259

260
/**
261
 * Extended concurrent test interface
262
 */
263
interface ItConcurrentExtended extends ItConcurrentBase {
264
  only: ItConcurrentBase;
265
  skip: ItConcurrentBase;
266
}
267

268
/**
269
 * Complete concurrent test interface
270
 */
271
interface ItConcurrent extends It {
272
  concurrent: ItConcurrentExtended;
273
}
274

275
/**
276
 * Base describe interface
277
 */
278
interface DescribeBase {
279
  (blockName: BlockNameLike, blockFn: BlockFn): void;
280
  each: Each<BlockFn>;
281
}
282

283
/**
284
 * Extended describe interface with modifiers
285
 */
286
interface Describe extends DescribeBase {
287
  only: DescribeBase;
288
  skip: DescribeBase;
289
}
290
```
291

292
### Global Framework Interface
293

294
Complete interface for Jest's global test framework functions.
295

296
```typescript { .api }
297
/**
298
 * All Jest global test framework functions
299
 */
300
interface TestFrameworkGlobals {
301
  it: ItConcurrent;
302
  test: ItConcurrent;
303
  fit: ItBase & { concurrent?: ItConcurrentBase };
304
  xit: ItBase;
305
  xtest: ItBase;
306
  describe: Describe;
307
  xdescribe: DescribeBase;
308
  fdescribe: DescribeBase;
309
  beforeAll: HookBase;
310
  beforeEach: HookBase;
311
  afterEach: HookBase;
312
  afterAll: HookBase;
313
}
314

315
/**
316
 * Coverage map data from istanbul-lib-coverage
317
 */
318
type CoverageMapData = Record<string, any>;
319

320
/**
321
 * Global additions including test framework and coverage
322
 */
323
interface GlobalAdditions extends TestFrameworkGlobals {
324
  __coverage__: CoverageMapData;
325
}
326

327
/**
328
 * Complete global scope with Jest additions
329
 */
330
interface Global extends GlobalAdditions, Omit<typeof globalThis, keyof GlobalAdditions> {
331
  [extras: PropertyKey]: unknown;
332
}
333
```
334

335
**Usage Examples:**
336

337
```typescript
338
import type { Global } from "@jest/types";
339

340
// Type a custom test function
341
const myTest: Global.TestFn = async () => {
342
  // Test implementation
343
};
344

345
// Type a done-based test
346
const doneTest: Global.DoneTakingTestFn = (done) => {
347
  setTimeout(() => {
348
    done();
349
  }, 100);
350
};
351

352
// Type a hook function
353
const setupHook: Global.HookFn = async () => {
354
  // Setup logic
355
};
356

357
// Type parameterized test data
358
const testData: Global.Table = [
359
  [1, 2, 3],
360
  [4, 5, 9],
361
];
362
```