0
# Jest
1

2
Jest is a comprehensive JavaScript testing framework designed for delightful testing experiences. It provides a complete testing solution that works out of the box for most JavaScript projects, featuring instant feedback through intelligent watch mode, powerful snapshot testing, extensive mocking capabilities, built-in code coverage reporting, and seamless integration with modern JavaScript tooling including Babel, TypeScript, webpack, and various bundlers.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { runCLI, createTestScheduler, SearchSource, getVersion, run, buildArgv } from "jest";
15
import type { Config } from "jest";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { runCLI, createTestScheduler, SearchSource, getVersion, run, buildArgv } = require("jest");
22
```
23

24
## Basic Usage
25

26
Jest can be used programmatically or via CLI:
27

28
```typescript
29
import { runCLI } from "jest";
30

31
// Run Jest programmatically
32
const { results, globalConfig } = await runCLI(
33
  { roots: ["<rootDir>/src"], testMatch: ["**/__tests__/**/*.test.js"] },
34
  ["./src"]
35
);
36

37
console.log(`Tests completed: ${results.numTotalTests}`);
38
console.log(`Tests passed: ${results.numPassedTests}`);
39
```
40

41
CLI usage:
42

43
```bash
44
# Run all tests
45
jest
46

47
# Run tests in watch mode
48
jest --watch
49

50
# Run with coverage
51
jest --coverage
52

53
# Run specific test files
54
jest user.test.js
55
```
56

57
## Architecture
58

59
Jest is built around several key components:
60

61
- **Test Runner**: Core engine that discovers, schedules, and executes tests
62
- **CLI Interface**: Command-line interface for running tests with extensive options
63
- **SearchSource**: Test file discovery and filtering system
64
- **TestScheduler**: Test execution scheduling and reporter management
65
- **Configuration System**: Flexible configuration for projects and global settings
66
- **Reporter System**: Extensible test result reporting and output formatting
67

68
## Capabilities
69

70
### Test Running and Execution
71

72
Core test running functionality including programmatic API and CLI runner with comprehensive test discovery and execution capabilities.
73

74
```typescript { .api }
75
function runCLI(
76
  argv: Config.Argv,
77
  projects: Array<string>
78
): Promise<{
79
  results: AggregatedResult;
80
  globalConfig: Config.GlobalConfig;
81
}>;
82

83
function run(maybeArgv?: Array<string>, project?: string): Promise<void>;
84
```
85

86
[Test Runner](./test-runner.md)
87

88
### CLI Usage and Options
89

90
Command-line interface providing over 70 options for test execution, coverage collection, watch mode, output formatting, and project configuration.
91

92
```typescript { .api }
93
function buildArgv(maybeArgv?: Array<string>): Promise<Config.Argv>;
94
```
95

96
[CLI Usage](./cli-usage.md)
97

98
### Test Discovery and Search
99

100
Advanced test file discovery system with pattern matching, dependency tracking, and change detection for optimized test runs.
101

102
```typescript { .api }
103
class SearchSource {
104
  constructor(context: TestContext);
105
  isTestFilePath(path: string): boolean;
106
  findMatchingTests(testPathPatternsExecutor: TestPathPatternsExecutor): SearchResult;
107
  findTestsByPaths(paths: Array<string>): SearchResult;
108
  findRelatedTests(allPaths: Set<string>, collectCoverage: boolean): Promise<SearchResult>;
109
}
110
```
111

112
[Test Discovery](./test-discovery.md)
113

114
### Configuration Management
115

116
Comprehensive configuration system supporting global settings, per-project configuration, and extensive customization options for all aspects of test execution.
117

118
```typescript { .api }
119
interface Config {
120
  // Main configuration interface (alias for Config.InitialOptions)
121
  testEnvironment?: string;
122
  testMatch?: Array<string>;
123
  transform?: Record<string, string>;
124
  setupFilesAfterEnv?: Array<string>;
125
  moduleNameMapping?: Record<string, string>;
126
  collectCoverage?: boolean;
127
}
128

129
interface Config.GlobalConfig {
130
  bail: number;
131
  collectCoverage: boolean;
132
  maxWorkers: number;
133
  rootDir: string;
134
  watch: boolean;
135
  watchAll: boolean;
136
}
137
```
138

139
[Configuration](./configuration.md)
140

141
### Test Scheduling and Reporting
142

143
Test execution scheduling with multi-process coordination, reporter management, and comprehensive result aggregation.
144

145
```typescript { .api }
146
function createTestScheduler(
147
  globalConfig: Config.GlobalConfig,
148
  context: TestSchedulerContext
149
): Promise<TestScheduler>;
150

151
class TestScheduler {
152
  constructor(globalConfig: Config.GlobalConfig, context: TestSchedulerContext);
153
  addReporter(reporter: Reporter): void;
154
  scheduleTests(tests: Array<Test>, watcher: TestWatcher): Promise<AggregatedResult>;
155
}
156
```
157

158
[Test Scheduling](./test-scheduling.md)
159

160
## Utility Functions
161

162
```typescript { .api }
163
function getVersion(): string;
164
```
165

166
Returns the current Jest version.
167

168
## Core Types
169

170
```typescript { .api }
171
interface AggregatedResult {
172
  numTotalTests: number;
173
  numPassedTests: number;
174
  numFailedTests: number;
175
  numPendingTests: number;
176
  numRuntimeErrorTestSuites: number;
177
  numTotalTestSuites: number;
178
  numPassedTestSuites: number;
179
  numFailedTestSuites: number;
180
  numPendingTestSuites: number;
181
  openHandles: Array<Error>;
182
  snapshot: SnapshotSummary;
183
  success: boolean;
184
  startTime: number;
185
  testResults: Array<TestResult>;
186
  wasInterrupted: boolean;
187
}
188

189
interface SearchResult {
190
  noSCM?: boolean;
191
  stats?: Stats;
192
  collectCoverageFrom?: Set<string>;
193
  tests: Array<Test>;
194
  total?: number;
195
}
196

197
interface TestContext {
198
  config: Config.ProjectConfig;
199
  hasteFS: IHasteFS;
200
  moduleMap: IModuleMap;
201
  resolver: IResolver;
202
}
203

204
interface TestSchedulerContext extends ReporterContext, TestRunnerContext {}
205

206
interface Test {
207
  context: TestContext;
208
  duration?: number;
209
  path: string;
210
}
211
```