0
# Test Framework Globals
1

2
Core testing functions for organizing and defining tests, providing the standard Jest API with support for skipping, focusing, concurrent execution, and parameterized tests.
3

4
## Capabilities
5

6
### Describe Function
7

8
Groups related tests together in a test suite.
9

10
```typescript { .api }
11
/**
12
 * Creates a test suite grouping related tests
13
 * @param blockName - Name or description of the test suite
14
 * @param blockFn - Function containing test definitions
15
 */
16
function describe(blockName: BlockNameLike, blockFn: BlockFn): void;
17

18
interface DescribeMethods {
19
  /** Run only this describe block */
20
  only(blockName: BlockNameLike, blockFn: BlockFn): void;
21
  /** Skip this entire describe block */
22
  skip(blockName: BlockNameLike, blockFn: BlockFn): void;
23
  /** Run parameterized describe blocks with different inputs */
24
  each<T extends readonly any[]>(
25
    table: ReadonlyArray<T>
26
  ): (name: string, fn: (...args: T) => void) => void;
27
}
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import { describe } from "jest-circus";
34

35
describe("Math operations", () => {
36
  // Tests go here
37
});
38

39
// Focus on specific suite
40
describe.only("Critical tests", () => {
41
  // Only this suite will run
42
});
43

44
// Skip entire suite
45
describe.skip("Broken tests", () => {
46
  // This suite will be skipped
47
});
48

49
// Parameterized describe blocks
50
describe.each([
51
  [1, 2, 3],
52
  [4, 5, 9],
53
])("Calculator with %i + %i", (a, b, expected) => {
54
  test(`equals ${expected}`, () => {
55
    expect(a + b).toBe(expected);
56
  });
57
});
58
```
59

60
### Test Functions
61

62
Define individual test cases.
63

64
```typescript { .api }
65
/**
66
 * Define a test case (alias for test)
67
 * @param testName - Name or description of the test
68
 * @param fn - Test function
69
 * @param timeout - Optional timeout in milliseconds
70
 */
71
function it(testName: TestNameLike, fn: TestFn, timeout?: number): void;
72

73
/**
74
 * Define a test case
75
 * @param testName - Name or description of the test  
76
 * @param fn - Test function
77
 * @param timeout - Optional timeout in milliseconds
78
 */
79
function test(testName: TestNameLike, fn: TestFn, timeout?: number): void;
80

81
interface TestMethods {
82
  /** Run only this test */
83
  only(testName: TestNameLike, fn: TestFn, timeout?: number): void;
84
  /** Skip this test */
85
  skip(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
86
  /** Mark test as TODO (not implemented) */
87
  todo(testName: TestNameLike, ...rest: Array<any>): void;
88
  /** Test expected to fail */
89
  failing(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
90
  /** Run parameterized tests with different inputs */
91
  each<T extends readonly any[]>(
92
    table: ReadonlyArray<T>
93
  ): (name: string, fn: (...args: T) => void, timeout?: number) => void;
94
  /** Run test concurrently */
95
  concurrent: ConcurrentTestFunction;
96
}
97

98
interface ConcurrentTestFunction {
99
  (testName: TestNameLike, fn: TestFn, timeout?: number): void;
100
  only(testName: TestNameLike, fn: TestFn, timeout?: number): void;  
101
  skip(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
102
  failing(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
103
  each<T extends readonly any[]>(
104
    table: ReadonlyArray<T>
105
  ): (name: string, fn: (...args: T) => void, timeout?: number) => void;
106
}
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
import { it, test } from "jest-circus";
113

114
// Basic test
115
test("should add numbers", () => {
116
  expect(1 + 2).toBe(3);
117
});
118

119
// it is an alias for test
120
it("should subtract numbers", () => {
121
  expect(5 - 3).toBe(2);
122
});
123

124
// Async test
125
test("should handle async operations", async () => {
126
  const result = await fetchData();
127
  expect(result).toBe("data");
128
});
129

130
// Test with custom timeout
131
test("slow test", async () => {
132
  await slowOperation();
133
}, 10000);
134

135
// Focus on specific test
136
test.only("important test", () => {
137
  expect(true).toBe(true);
138
});
139

140
// Skip test
141
test.skip("broken test", () => {
142
  // This test will be skipped
143
});
144

145
// TODO test
146
test.todo("implement this feature");
147

148
// Failing test (expected to fail)
149
test.failing("known bug", () => {
150
  expect(buggyFunction()).toBe("correct");
151
});
152

153
// Concurrent test execution
154
test.concurrent("parallel test 1", async () => {
155
  const result = await asyncOperation1();
156
  expect(result).toBe("result1");
157
});
158

159
test.concurrent("parallel test 2", async () => {
160
  const result = await asyncOperation2();
161
  expect(result).toBe("result2");
162
});
163

164
// Parameterized tests
165
test.each([
166
  [1, 1, 2],
167
  [1, 2, 3], 
168
  [2, 1, 3],
169
])(".add(%i, %i)", (a, b, expected) => {
170
  expect(a + b).toBe(expected);
171
});
172
```
173

174
### Lifecycle Hooks
175

176
Setup and teardown functions that run at specific points in the test lifecycle.
177

178
```typescript { .api }
179
/**
180
 * Run once before all tests in the current describe block
181
 * @param fn - Hook function
182
 * @param timeout - Optional timeout in milliseconds
183
 */
184
function beforeAll(fn: HookFn, timeout?: number): void;
185

186
/**
187
 * Run once after all tests in the current describe block
188
 * @param fn - Hook function
189
 * @param timeout - Optional timeout in milliseconds
190
 */
191
function afterAll(fn: HookFn, timeout?: number): void;
192

193
/**
194
 * Run before each test in the current describe block
195
 * @param fn - Hook function
196
 * @param timeout - Optional timeout in milliseconds
197
 */
198
function beforeEach(fn: HookFn, timeout?: number): void;
199

200
/**
201
 * Run after each test in the current describe block
202
 * @param fn - Hook function
203
 * @param timeout - Optional timeout in milliseconds
204
 */
205
function afterEach(fn: HookFn, timeout?: number): void;
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { describe, test, beforeAll, afterAll, beforeEach, afterEach } from "jest-circus";
212

213
describe("Database tests", () => {
214
  let database;
215

216
  beforeAll(async () => {
217
    // Setup database connection once
218
    database = await createConnection();
219
  });
220

221
  afterAll(async () => {
222
    // Close database connection
223
    await database.close();
224
  });
225

226
  beforeEach(async () => {
227
    // Clean database before each test
228
    await database.clean();
229
  });
230

231
  afterEach(async () => {
232
    // Optional cleanup after each test
233
    await database.resetState();
234
  });
235

236
  test("should insert user", async () => {
237
    const user = await database.insertUser({ name: "John" });
238
    expect(user.id).toBeDefined();
239
  });
240

241
  test("should find user", async () => {
242
    await database.insertUser({ name: "Jane" });
243
    const user = await database.findUser({ name: "Jane" });
244
    expect(user).toBeTruthy();
245
  });
246
});
247

248
// Hooks with custom timeout
249
beforeAll(async () => {
250
  await slowSetup();
251
}, 30000); // 30 second timeout
252
```
253

254
## Types
255

256
```typescript { .api }
257
type BlockNameLike = string | Function;
258
type TestNameLike = string | Function;
259

260
type BlockFn = () => void;
261
type TestFn = (done?: DoneFn) => void | Promise<void>;
262
type HookFn = (done?: DoneFn) => void | Promise<void>;
263
type DoneFn = (reason?: string | Error) => void;
264

265
type BlockMode = void | 'skip' | 'only' | 'todo';
266
type TestMode = BlockMode;
267
```