0
# Test Execution
1

2
Core test execution engine that runs tests and produces results. This module provides the main entry point for executing test suites and handling test lifecycle management.
3

4
## Capabilities
5

6
### Run Function
7

8
Main test execution function that processes the test suite and returns results.
9

10
```typescript { .api }
11
/**
12
 * Execute all tests in the current test suite
13
 * @returns Promise resolving to test execution results
14
 */
15
function run(): Promise<RunResult>;
16

17
interface RunResult {
18
  /** Array of unhandled errors that occurred during execution */
19
  unhandledErrors: Array<FormattedError>;
20
  /** Array of individual test results */
21
  testResults: Array<TestResult>;
22
}
23

24
interface TestResult {
25
  /** Test duration in milliseconds */
26
  duration?: number | null;
27
  /** Error messages if test failed */
28
  errors: Array<FormattedError>;
29
  /** Detailed error information */
30
  errorsDetailed: Array<unknown>;
31
  /** Number of times test was invoked */
32
  invocations: number;
33
  /** Test status */
34
  status: 'skip' | 'done' | 'todo';
35
  /** Location information */
36
  location?: {column: number; line: number} | null;
37
  /** Number of passing assertions */
38
  numPassingAsserts: number;
39
  /** Retry error reasons */
40
  retryReasons: Array<FormattedError>;
41
  /** Path of test names from root describe to test */
42
  testPath: Array<string>;
43
}
44

45
type FormattedError = string;
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import { run } from "jest-circus";
52

53
// Execute all tests
54
const results = await run();
55

56
const passedTests = results.testResults.filter(t => t.status === 'done' && t.errors.length === 0);
57
const failedTests = results.testResults.filter(t => t.errors.length > 0);
58
const skippedTests = results.testResults.filter(t => t.status === 'skip');
59

60
console.log(`Tests passed: ${passedTests.length}`);
61
console.log(`Tests failed: ${failedTests.length}`);
62
console.log(`Tests skipped: ${skippedTests.length}`);
63

64
if (results.unhandledErrors.length > 0) {
65
  console.error("Unhandled errors:", results.unhandledErrors);
66
}
67

68
// Process individual test results
69
results.testResults.forEach(testResult => {
70
  if (testResult.errors.length > 0) {
71
    console.error(`Failed: ${testResult.testPath.join(' > ')}`);
72
    console.error(testResult.errors.join('\n'));
73
  }
74
});
75
```
76

77
## Jest Adapter Integration
78

79
Jest adapter for integrating circus with Jest's test runner infrastructure.
80

81
```typescript { .api }
82
/**
83
 * Jest test runner adapter function
84
 * @param globalConfig - Jest global configuration
85
 * @param config - Project-specific configuration
86
 * @param environment - Test environment instance
87
 * @param runtime - Jest runtime instance
88
 * @param testPath - Path to the test file
89
 * @param sendMessageToJest - Optional message handler
90
 * @returns Promise resolving to test results
91
 */
92
function jestAdapter(
93
  globalConfig: GlobalConfig,
94
  config: ProjectConfig,
95
  environment: JestEnvironment,
96
  runtime: Runtime,
97
  testPath: string,
98
  sendMessageToJest?: TestFileEvent
99
): Promise<TestResult>;
100

101
interface GlobalConfig {
102
  /** Maximum number of concurrent workers */
103
  maxWorkers: number;
104
  /** Whether to run tests in watch mode */
105
  watch: boolean;
106
  /** Whether to run tests in watch all mode */
107
  watchAll: boolean;
108
  /** Test timeout in milliseconds */
109
  testTimeout: number;
110
  /** Other global configuration options */
111
  [key: string]: any;
112
}
113

114
interface ProjectConfig {
115
  /** Test runner to use */
116
  testRunner: string;
117
  /** Test environment */
118
  testEnvironment: string;
119
  /** Setup files to run after environment setup */
120
  setupFilesAfterEnv: Array<string>;
121
  /** Whether to reset modules between tests */
122
  resetModules: boolean;
123
  /** Whether to clear mocks between tests */
124
  clearMocks: boolean;
125
  /** Whether to reset mocks between tests */
126
  resetMocks: boolean;
127
  /** Whether to restore mocks between tests */
128
  restoreMocks: boolean;
129
  /** Fake timers configuration */
130
  fakeTimers: {
131
    enableGlobally: boolean;
132
    legacyFakeTimers: boolean;
133
  };
134
  /** Other project configuration options */
135
  [key: string]: any;
136
}
137

138
interface TestResult {
139
  /** Test execution results */
140
  testResults: Array<AssertionResult>;
141
  /** Coverage information if collected */
142
  coverage?: any;
143
  /** Performance timing information */
144
  perfStats: {
145
    start: number;
146
    end: number;
147
    runtime: number;
148
    slow: boolean;
149
  };
150
  /** Snapshot data */
151
  snapshot: {
152
    added: number;
153
    fileDeleted: boolean;
154
    matched: number;
155
    unchecked: number;
156
    uncheckedKeys: Array<string>;
157
    unmatched: number;
158
    updated: number;
159
  };
160
  /** Source maps for coverage */
161
  sourceMaps?: any;
162
  /** Whether test execution was skipped */
163
  skipped: boolean;
164
  /** Other test result data */
165
  [key: string]: any;
166
}
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
// The Jest adapter is typically used internally by Jest
173
// when configured as the test runner:
174

175
// jest.config.js
176
module.exports = {
177
  testRunner: 'jest-circus/runner'
178
};
179

180
// Or via CLI:
181
// jest --testRunner='jest-circus/runner'
182

183
// The adapter can also be used programmatically:
184
import jestAdapter from 'jest-circus/runner';
185

186
const result = await jestAdapter(
187
  globalConfig,
188
  projectConfig, 
189
  environment,
190
  runtime,
191
  '/path/to/test.js'
192
);
193
```
194

195
## Runner Configuration
196

197
Configuration options for customizing test execution behavior.
198

199
```typescript { .api }
200
interface RunnerConfig {
201
  /** Maximum number of tests to run concurrently */
202
  maxConcurrency?: number;
203
  /** Default test timeout in milliseconds */
204
  testTimeout?: number;
205
  /** Random seed for test shuffling */
206
  seed?: number;
207
  /** Whether to randomize test order */
208
  randomize?: boolean;
209
  /** Pattern to match test names */
210
  testNamePattern?: string | RegExp;
211
  /** Whether to include test location in results */
212
  includeTestLocationInResult?: boolean;
213
}
214
```
215

216
**Usage Examples:**
217

218
```typescript
219
import { setState, getState } from "jest-circus";
220

221
// Configure test execution
222
const currentState = getState();
223
setState({
224
  ...currentState,
225
  maxConcurrency: 5,      // Run up to 5 tests concurrently
226
  testTimeout: 10000,     // 10 second default timeout
227
  seed: 12345,            // Fixed seed for reproducible test order
228
  testNamePattern: /api/, // Only run tests matching "api"
229
  includeTestLocationInResult: true
230
});
231
```