0
# Test Scheduling
1

2
Test execution coordination system providing reporter management, test scheduling, and result aggregation. The TestScheduler handles parallel execution, result reporting, and error handling for Jest test runs.
3

4
## Capabilities
5

6
### Test Scheduler Creation
7

8
Factory function for creating configured TestScheduler instances with reporter setup.
9

10
```typescript { .api }
11
/**
12
 * Creates and initializes a TestScheduler with reporters setup
13
 * @param globalConfig - Jest global configuration
14
 * @param context - Combined reporter and test runner context
15
 * @returns Promise resolving to configured TestScheduler instance
16
 */
17
export async function createTestScheduler(
18
  globalConfig: Config.GlobalConfig,
19
  context: TestSchedulerContext
20
): Promise<TestScheduler>;
21
```
22

23
**Usage Example:**
24

25
```typescript
26
import { createTestScheduler } from "@jest/core";
27
import { Config } from "@jest/types";
28

29
// Setup configuration and context
30
const globalConfig: Config.GlobalConfig = {
31
  maxWorkers: 4,
32
  verbose: true,
33
  coverage: false,
34
  // ... other global config options
35
};
36

37
const context: TestSchedulerContext = {
38
  // Reporter context
39
  // Test runner context
40
  // ... context properties
41
};
42

43
// Create scheduler with automatic reporter setup
44
const scheduler = await createTestScheduler(globalConfig, context);
45
```
46

47
### TestScheduler Class
48

49
Core class managing test execution, reporters, and result aggregation. TestScheduler instances are created exclusively through the `createTestScheduler` factory function and cannot be instantiated directly.
50

51
```typescript { .api }
52
/**
53
 * Manages test execution scheduling and reporting
54
 * Note: TestScheduler is not directly exported - use createTestScheduler() to obtain instances
55
 */
56
interface TestScheduler {
57
  addReporter(reporter: Reporter): void;
58
  removeReporter(reporterConstructor: ReporterConstructor): void;
59
  scheduleTests(tests: Array<Test>, watcher: TestWatcher): Promise<AggregatedResult>;
60
}
61
```
62

63
### Reporter Management
64

65
Add and remove reporters from the test execution pipeline.
66

67
```typescript { .api }
68
/**
69
 * Adds a reporter to the test execution pipeline
70
 * @param reporter - Reporter instance to add
71
 */
72
addReporter(reporter: Reporter): void;
73

74
/**
75
 * Removes a reporter from the execution pipeline
76
 * @param reporterConstructor - Constructor of the reporter to remove
77
 */
78
removeReporter(reporterConstructor: ReporterConstructor): void;
79
```
80

81
**Usage Example:**
82

83
```typescript
84
import { DefaultReporter, VerboseReporter } from "@jest/reporters";
85

86
// Add reporters
87
const defaultReporter = new DefaultReporter(globalConfig, {}, context);
88
scheduler.addReporter(defaultReporter);
89

90
const verboseReporter = new VerboseReporter(globalConfig, {}, context);
91
scheduler.addReporter(verboseReporter);
92

93
// Remove a reporter
94
scheduler.removeReporter(VerboseReporter);
95
```
96

97
### Test Execution Scheduling
98

99
Schedule and execute a collection of tests with comprehensive result reporting.
100

101
```typescript { .api }
102
/**
103
 * Schedules and executes a collection of tests
104
 * @param tests - Array of test files to execute
105
 * @param watcher - Test watcher for handling interruptions and watch mode
106
 * @returns Promise resolving to aggregated test results
107
 */
108
async scheduleTests(
109
  tests: Array<Test>, 
110
  watcher: TestWatcher
111
): Promise<AggregatedResult>;
112
```
113

114
**Usage Example:**
115

116
```typescript
117
import { TestWatcher } from "jest-watcher";
118

119
// Prepare tests (from SearchSource)
120
const tests: Array<Test> = [
121
  {
122
    context: testContext,
123
    path: "/src/__tests__/example.test.js",
124
    duration: undefined,
125
  },
126
  // ... more tests
127
];
128

129
// Create test watcher
130
const watcher = new TestWatcher({ isWatchMode: false });
131

132
// Schedule and execute tests
133
const results = await scheduler.scheduleTests(tests, watcher);
134

135
console.log(`Total tests: ${results.numTotalTests}`);
136
console.log(`Passed: ${results.numPassedTests}`);
137
console.log(`Failed: ${results.numFailedTests}`);
138
console.log(`Success: ${results.success}`);
139
```
140

141
## Advanced Usage
142

143
### Custom Reporter Integration
144

145
```typescript
146
import { BaseReporter } from "@jest/reporters";
147
import type { AggregatedResult, Test, TestResult } from "@jest/test-result";
148

149
class CustomReporter extends BaseReporter {
150
  onRunStart(aggregatedResult: AggregatedResult): void {
151
    console.log("Test run started");
152
  }
153

154
  onTestFileStart(test: Test): void {
155
    console.log(`Starting test: ${test.path}`);
156
  }
157

158
  onTestFileResult(test: Test, testResult: TestResult): void {
159
    console.log(`Finished test: ${test.path}, passed: ${testResult.numPassingTests}`);
160
  }
161

162
  onRunComplete(aggregatedResult: AggregatedResult): void {
163
    console.log("Test run completed");
164
  }
165
}
166

167
// Add custom reporter
168
const customReporter = new CustomReporter(globalConfig, {}, context);
169
scheduler.addReporter(customReporter);
170
```
171

172
### Handling Test Execution Results
173

174
```typescript
175
const results = await scheduler.scheduleTests(tests, watcher);
176

177
// Check for failures
178
if (!results.success) {
179
  console.error(`${results.numFailedTests} tests failed`);
180
  
181
  // Examine individual test results
182
  results.testResults.forEach(testResult => {
183
    if (testResult.numFailingTests > 0) {
184
      console.log(`Failed test file: ${testResult.testFilePath}`);
185
      testResult.testResults.forEach(assertionResult => {
186
        if (assertionResult.status === 'failed') {
187
          console.log(`  Failed test: ${assertionResult.fullName}`);
188
          console.log(`  Error: ${assertionResult.failureMessages[0]}`);
189
        }
190
      });
191
    }
192
  });
193
}
194

195
// Check for open handles
196
if (results.openHandles && results.openHandles.length > 0) {
197
  console.warn(`${results.openHandles.length} open handles detected`);
198
}
199
```
200

201
## Types
202

203
```typescript { .api }
204
type TestSchedulerContext = ReporterContext & TestRunnerContext;
205

206
type ReporterConstructor = new (
207
  globalConfig: Config.GlobalConfig,
208
  reporterConfig: Record<string, unknown>,
209
  reporterContext: ReporterContext
210
) => JestReporter;
211

212
interface AggregatedResult {
213
  /** Number of failed individual tests */
214
  numFailedTests: number;
215
  /** Number of failed test suites */
216
  numFailedTestSuites: number;
217
  /** Number of passed individual tests */
218
  numPassedTests: number;
219
  /** Number of passed test suites */
220
  numPassedTestSuites: number;
221
  /** Number of pending individual tests */
222
  numPendingTests: number;
223
  /** Number of pending test suites */
224
  numPendingTestSuites: number;
225
  /** Number of test suites with runtime errors */
226
  numRuntimeErrorTestSuites: number;
227
  /** Total number of individual tests */
228
  numTotalTests: number;
229
  /** Total number of test suites */
230
  numTotalTestSuites: number;
231
  /** Array of open handles that may prevent Jest from exiting */
232
  openHandles: Array<Error>;
233
  /** Snapshot test summary */
234
  snapshot: SnapshotSummary;
235
  /** Test run start time */
236
  startTime: number;
237
  /** Whether the test run was successful */
238
  success: boolean;
239
  /** Array of individual test file results */
240
  testResults: Array<TestResult>;
241
  /** Whether the test run was interrupted */
242
  wasInterrupted: boolean;
243
}
244

245
interface SnapshotSummary {
246
  added: number;
247
  didUpdate: boolean;
248
  failure: boolean;
249
  filesAdded: number;
250
  filesRemoved: number;
251
  filesRemovedList: Array<string>;
252
  filesUnmatched: number;
253
  filesUpdated: number;
254
  matched: number;
255
  total: number;
256
  unchecked: number;
257
  uncheckedKeysByFile: Array<{
258
    filePath: string;
259
    keys: Array<string>;
260
  }>;
261
  unmatched: number;
262
  updated: number;
263
}
264
```