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
```