0
# Jest Core
1

2
Jest Core provides the foundational functionality for Jest, a comprehensive JavaScript testing framework. It offers programmatic APIs for test discovery, test scheduling, and CLI integration, enabling developers to build custom testing workflows and integrate Jest into build tools and IDEs.
3

4
## Package Information
5

6
- **Package Name**: @jest/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jest/core`
10

11
## Core Imports
12

13
```typescript
14
import { SearchSource, createTestScheduler, runCLI, getVersion } from "@jest/core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { SearchSource, createTestScheduler, runCLI, getVersion } = require("@jest/core");
21
```
22

23
## Basic Usage
24

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

29
// Run Jest programmatically with CLI-like interface
30
const argv: Config.Argv = {
31
  // Jest CLI arguments
32
  testMatch: ["**/__tests__/**/*.test.js"],
33
  coverage: true,
34
  verbose: true,
35
};
36

37
const projects = ["./my-project"];
38

39
const { results, globalConfig } = await runCLI(argv, projects);
40
console.log(`Tests: ${results.numTotalTests}, Failures: ${results.numFailedTests}`);
41
```
42

43
## Architecture
44

45
Jest Core is built around several key components:
46

47
- **Test Discovery**: `SearchSource` class handles finding and filtering test files based on patterns and configurations
48
- **Test Scheduling**: `TestScheduler` manages test execution coordination, reporter management, and result aggregation
49
- **CLI Integration**: `runCLI` function provides command-line interface compatibility for programmatic usage
50
- **Configuration System**: Deep integration with Jest's configuration system via `@jest/types` Config interfaces
51
- **Reporter System**: Built-in support for multiple reporters and custom reporter registration
52

53
## Capabilities
54

55
### Test Discovery and Search
56

57
Core functionality for finding and filtering test files based on patterns, changed files, and dependencies. Essential for watch mode, selective test running, and IDE integration.
58

59
```typescript { .api }
60
export default class SearchSource {
61
  constructor(context: TestContext);
62
  isTestFilePath(path: string): boolean;
63
  findMatchingTests(testPathPatternsExecutor: TestPathPatternsExecutor): SearchResult;
64
  async findRelatedTests(allPaths: Set<string>, collectCoverage: boolean): Promise<SearchResult>;
65
  findTestsByPaths(paths: Array<string>): SearchResult;
66
}
67

68
export type SearchResult = {
69
  noSCM?: boolean;
70
  stats?: Stats;
71
  collectCoverageFrom?: Set<string>;
72
  tests: Array<Test>;
73
  total?: number;
74
};
75
```
76

77
[Test Discovery](./test-discovery.md)
78

79
### Test Scheduling and Execution
80

81
Test execution coordination system providing reporter management, test scheduling, and result aggregation. Handles parallel execution, result reporting, and error handling.
82

83
```typescript { .api }
84
export async function createTestScheduler(
85
  globalConfig: Config.GlobalConfig,
86
  context: TestSchedulerContext
87
): Promise<TestScheduler>;
88
```
89

90
[Test Scheduling](./test-scheduling.md)
91

92
### CLI Integration
93

94
Programmatic interface to Jest's command-line functionality, supporting all CLI options and returning structured results. Perfect for build tools, CI systems, and custom test runners.
95

96
```typescript { .api }
97
export async function runCLI(
98
  argv: Config.Argv,
99
  projects: Array<string>
100
): Promise<{
101
  results: AggregatedResult;
102
  globalConfig: Config.GlobalConfig;
103
}>;
104
```
105

106
[CLI Integration](./cli-integration.md)
107

108
### Utility Functions
109

110
Helper functions for version information and other utilities.
111

112
```typescript { .api }
113
export default function getVersion(): string;
114
```
115

116
## Core Types
117

118
```typescript { .api }
119
interface TestContext {
120
  config: Config.ProjectConfig;
121
  hasteFS: IHasteFS;
122
  moduleMap: IModuleMap;
123
  resolver: IResolver;
124
}
125

126
interface Test {
127
  context: TestContext;
128
  duration?: number;
129
  path: string;
130
}
131

132
interface AggregatedResult {
133
  numFailedTests: number;
134
  numFailedTestSuites: number;
135
  numPassedTests: number;
136
  numPassedTestSuites: number;
137
  numPendingTests: number;
138
  numPendingTestSuites: number;
139
  numRuntimeErrorTestSuites: number;
140
  numTotalTests: number;
141
  numTotalTestSuites: number;
142
  openHandles: Array<Error>;
143
  snapshot: SnapshotSummary;
144
  startTime: number;
145
  success: boolean;
146
  testResults: Array<TestResult>;
147
  wasInterrupted: boolean;
148
}
149

150
interface Stats {
151
  roots: number;
152
  testMatch: number;
153
  testPathIgnorePatterns: number;
154
  testRegex: number;
155
  testPathPatterns?: number;
156
}
157

158
type TestSchedulerContext = ReporterContext & TestRunnerContext;
159

160
type ReporterConstructor = new (
161
  globalConfig: Config.GlobalConfig,
162
  reporterConfig: Record<string, unknown>,
163
  reporterContext: ReporterContext
164
) => JestReporter;
165

166
type Filter = (testPaths: Array<string>) => Promise<{
167
  filtered: Array<string>;
168
}>;
169

170
interface TestScheduler {
171
  addReporter(reporter: Reporter): void;
172
  removeReporter(reporterConstructor: ReporterConstructor): void;
173
  scheduleTests(tests: Array<Test>, watcher: TestWatcher): Promise<AggregatedResult>;
174
}
175
```