0
# Jasmine
1

2
Jasmine is a Node.js CLI and supporting code for running Jasmine specs under Node. It provides both sequential and parallel test execution capabilities, with extensive configuration options, filtering, and reporting features. The package acts as a wrapper around jasmine-core, providing Node.js-specific functionality including file loading, configuration management, and process orchestration.
3

4
## Package Information
5

6
- **Package Name**: jasmine
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install --save-dev jasmine`
10

11
## Core Imports
12

13
```javascript
14
const Jasmine = require('jasmine');
15
const ParallelRunner = require('jasmine/parallel');
16
const { ConsoleReporter } = require('jasmine');
17
```
18

19
For ES modules:
20

21
```javascript
22
import Jasmine from 'jasmine';
23
import ParallelRunner from 'jasmine/parallel';
24
```
25

26
## Basic Usage
27

28
```javascript
29
const Jasmine = require('jasmine');
30

31
const jasmine = new Jasmine();
32
jasmine.loadConfigFile(); // loads spec/support/jasmine.json by default
33
jasmine.execute();
34
```
35

36
For parallel execution:
37

38
```javascript
39
const ParallelRunner = require('jasmine/parallel');
40

41
const runner = new ParallelRunner({ numWorkers: 4 });
42
runner.loadConfigFile();
43
runner.execute();
44
```
45

46
## CLI Usage
47

48
Initialize a project:
49
```bash
50
npx jasmine init
51
```
52

53
Install examples:
54
```bash
55
npx jasmine examples
56
```
57

58
Run tests:
59
```bash
60
npx jasmine
61
npx jasmine spec/my-spec.js
62
npx jasmine --parallel=4
63
npx jasmine --filter="integration"
64
```
65

66
## Architecture
67

68
Jasmine is built around several key components:
69

70
- **Sequential Runner**: `Jasmine` class providing single-process test execution with full jasmine-core integration
71
- **Parallel Runner**: `ParallelRunner` class distributing specs across multiple worker processes for faster execution
72
- **Configuration System**: Flexible configuration loading from JSON/JS files with CLI override support
73
- **Reporting System**: Built-in console reporter with support for custom reporters and parallel aggregation
74
- **CLI Interface**: Full-featured command-line tool with sub-commands and extensive options
75
- **Module Loading**: Sophisticated ES module and CommonJS loading with automatic format detection
76

77
## Capabilities
78

79
### Sequential Test Execution
80

81
Core test runner providing full control over test execution with jasmine-core integration, custom matchers, and flexible configuration.
82

83
```javascript { .api }
84
class Jasmine {
85
  constructor(options?: JasmineOptions);
86
  execute(files?: string[], filter?: string | RegExp | FilterObject): Promise<JasmineDoneInfo>;
87
  enumerate(): Promise<EnumeratedSuiteOrSpec[]>;
88
  randomizeTests(value: boolean): void;
89
  seed(value: string): void;
90
  addReporter(reporter: Reporter): void;
91
  clearReporters(): void;
92
  addMatchers(matchers: CustomMatchers): void;
93
  readonly env: Env;
94
  exitOnCompletion: boolean;
95
}
96

97
interface JasmineOptions {
98
  projectBaseDir?: string;
99
  globals?: boolean;
100
}
101
```
102

103
[Sequential Runner](./sequential-runner.md)
104

105
### Parallel Test Execution
106

107
High-performance parallel test execution distributing specs across multiple worker processes with automatic load balancing.
108

109
```javascript { .api }
110
class ParallelRunner {
111
  constructor(options?: ParallelRunnerOptions);
112
  execute(files?: string[], filterString?: string): Promise<JasmineDoneInfo>;
113
  addReporter(reporter: Reporter, errorContext?: string): void;
114
  clearReporters(): void;
115
  exitOnCompletion: boolean;
116
}
117

118
interface ParallelRunnerOptions {
119
  projectBaseDir?: string;
120
  numWorkers?: number;
121
  globals?: boolean;
122
}
123
```
124

125
[Parallel Runner](./parallel-runner.md)
126

127
### Configuration Management
128

129
Comprehensive configuration system supporting JSON and JavaScript config files with CLI overrides and environment variable support.
130

131
```javascript { .api }
132
interface Configuration {
133
  spec_dir?: string;
134
  spec_files?: string[];
135
  helpers?: string[];
136
  requires?: string[];
137
  jsLoader?: 'import' | 'require';
138
  failSpecWithNoExpectations?: boolean;
139
  stopSpecOnExpectationFailure?: boolean;
140
  stopOnSpecFailure?: boolean;
141
  alwaysListPendingSpecs?: boolean;
142
  random?: boolean;
143
  verboseDeprecations?: boolean;
144
  reporters?: Reporter[];
145
  globalSetup?: () => void | Promise<void>;
146
  globalSetupTimeout?: number;
147
  globalTeardown?: () => void | Promise<void>;
148
  globalTeardownTimeout?: number;
149
  env?: EnvConfig;
150
}
151
```
152

153
[Configuration](./configuration.md)
154

155
### Command Line Interface
156

157
Full-featured CLI with sub-commands, extensive options, and environment variable support for integrating Jasmine into development workflows.
158

159
```bash { .api }
160
jasmine [command] [options] [files]
161

162
Commands:
163
  init        Initialize jasmine project
164
  examples    Install example specs
165
  help, -h    Show help
166
  version, -v Show versions
167
  enumerate   List suites and specs
168

169
Options:
170
  --parallel=N        Run in parallel with N workers
171
  --no-color/--color  Control color output
172
  --filter=REGEX      Filter specs by regex
173
  --filter-path=JSON  Filter specs by path
174
  --helper=PATTERN    Load helper files
175
  --require=MODULE    Require modules  
176
  --fail-fast         Stop on first failure
177
  --config=PATH       Specify config file
178
  --reporter=PATH     Use custom reporter
179
  --verbose           Enable verbose output
180
```
181

182
[Command Line Interface](./cli.md)
183

184
### Reporting System
185

186
Built-in console reporter with support for custom reporters, parallel execution aggregation, and detailed failure reporting.
187

188
```javascript { .api }
189
class ConsoleReporter {
190
  constructor();
191
  setOptions(options: ConsoleReporterOptions): void;
192
  jasmineStarted(options: any): void;
193
  jasmineDone(result: JasmineDoneInfo): void;
194
  specDone(result: SpecResult): void;
195
  suiteDone(result: SuiteResult): void;
196
  reporterCapabilities: { parallel: boolean };
197
}
198

199
interface ConsoleReporterOptions {
200
  showColors?: boolean;
201
  print?: (text: string) => void;
202
  stackFilter?: (stack: string) => string;
203
  randomSeedReproductionCmd?: (seed: string) => string;
204
  alwaysListPendingSpecs?: boolean;
205
}
206
```
207

208
[Reporting](./reporting.md)
209

210
## Common Types
211

212
```javascript { .api }
213
interface JasmineDoneInfo {
214
  overallStatus: 'passed' | 'failed' | 'incomplete';
215
  totalTime?: number;
216
  numWorkers?: number;
217
  failedExpectations: FailedExpectation[];
218
  deprecationWarnings: DeprecationWarning[];
219
  incompleteCode?: string;
220
  incompleteReason?: string;
221
}
222

223
interface EnumeratedSuiteOrSpec {
224
  type: 'suite' | 'spec';
225
  description: string;
226
  children?: EnumeratedSuiteOrSpec[];
227
}
228

229
interface FilterObject {
230
  path: string[];
231
}
232

233
interface FailedExpectation {
234
  actual: any;
235
  expected: any;
236
  globalErrorType?: string;
237
  matcherName: string;
238
  message: string;
239
  passed: false;
240
  stack: string;
241
}
242

243
interface DeprecationWarning {
244
  message: string;
245
  stack?: string;
246
}
247

248
interface Reporter {
249
  jasmineStarted?(suiteInfo: JasmineStartedInfo): void;
250
  jasmineDone?(result: JasmineDoneInfo): void;
251
  specDone?(result: SpecResult): void;
252
  suiteDone?(result: SuiteResult): void;
253
  reporterCapabilities?: { parallel?: boolean };
254
}
255

256
interface JasmineStartedInfo {
257
  totalSpecsDefined?: number;
258
  order?: {
259
    random: boolean;
260
    seed: string;
261
  };
262
  parallel?: boolean;
263
}
264

265
interface SpecResult {
266
  id: string;
267
  description: string;
268
  fullName: string;
269
  failedExpectations: FailedExpectation[];
270
  passedExpectations: PassedExpectation[];
271
  pendingReason?: string;
272
  status: 'passed' | 'failed' | 'pending' | 'disabled';
273
  debugLogs?: DebugLogEntry[];
274
  duration?: number;
275
}
276

277
interface SuiteResult {
278
  id: string;
279
  description: string;
280
  fullName: string;
281
  failedExpectations: FailedExpectation[];
282
  status: 'passed' | 'failed' | 'disabled';
283
}
284

285
interface PassedExpectation {
286
  matcherName: string;
287
  message: string;
288
  stack: string;
289
  passed: true;
290
}
291

292
interface DebugLogEntry {
293
  timestamp: number;
294
  message: string;
295
}
296

297
interface CustomMatchers {
298
  [matcherName: string]: (util?: MatchersUtil, customEqualityTesters?: CustomEqualityTester[]) => {
299
    compare(actual: any, expected?: any): MatcherResult;
300
    negativeCompare?(actual: any, expected?: any): MatcherResult;
301
  };
302
}
303

304
interface MatcherResult {
305
  pass: boolean;
306
  message?: string | (() => string);
307
}
308

309
interface MatchersUtil {
310
  equals(a: any, b: any, customTesters?: CustomEqualityTester[]): boolean;
311
  contains(haystack: any, needle: any, customTesters?: CustomEqualityTester[]): boolean;
312
  buildFailureMessage(matcherName: string, isNot: boolean, actual: any, ...expected: any[]): string;
313
}
314

315
interface CustomEqualityTester {
316
  (first: any, second: any): boolean | void;
317
}
318

319
interface EnvConfig {
320
  failSpecWithNoExpectations?: boolean;
321
  stopSpecOnExpectationFailure?: boolean;
322
  stopOnSpecFailure?: boolean;
323
  random?: boolean;
324
  verboseDeprecations?: boolean;
325
  forbidDuplicateNames?: boolean;
326
  throwOnExpectationFailure?: boolean;
327
  hideDisabled?: boolean;
328
}
329
```