0
# Mocha
1
2
Mocha is a feature-rich JavaScript testing framework that runs on Node.js and in browsers. It provides flexible test organization with BDD/TDD interfaces, extensive reporting options, asynchronous testing support, and parallel execution capabilities for improved performance.
3
4
## Package Information
5
6
- **Package Name**: mocha
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mocha`
10
11
## Core Imports
12
13
```javascript
14
const { Mocha } = require('mocha');
15
const mocha = require('mocha');
16
```
17
18
For ES modules:
19
20
```javascript
21
import Mocha from 'mocha';
22
import { describe, it, before, after, beforeEach, afterEach } from 'mocha';
23
```
24
25
Browser (via script tag):
26
27
```html
28
<script src="node_modules/mocha/mocha.js"></script>
29
<script>
30
mocha.setup('bdd');
31
</script>
32
```
33
34
## Basic Usage
35
36
```javascript
37
const { describe, it } = require('mocha');
38
const assert = require('assert');
39
40
describe('Array', function() {
41
describe('#indexOf()', function() {
42
it('should return -1 when the value is not present', function() {
43
assert.equal([1, 2, 3].indexOf(4), -1);
44
});
45
46
it('should return the correct index when value is present', function() {
47
assert.equal([1, 2, 3].indexOf(2), 1);
48
});
49
});
50
});
51
```
52
53
## Architecture
54
55
Mocha is built around several key components:
56
57
- **Interfaces**: Different styles for writing tests (BDD, TDD, QUnit, Exports)
58
- **Test Organization**: Hierarchical structure with suites and tests
59
- **Execution Engine**: Runner class that manages test execution and events
60
- **Reporting System**: Pluggable reporters for different output formats
61
- **Hook System**: Before/after hooks for setup and teardown at various levels
62
- **Configuration**: Flexible options system supporting files, CLI args, and programmatic setup
63
64
## Capabilities
65
66
### Test Organization and Interfaces
67
68
Mocha supports multiple interfaces for organizing tests, with BDD being the default. Each interface provides different syntax styles for defining test suites and cases.
69
70
```javascript { .api }
71
// BDD Interface (default)
72
function describe(title, fn);
73
function it(title, fn);
74
function before(fn);
75
function after(fn);
76
function beforeEach(fn);
77
function afterEach(fn);
78
79
// TDD Interface
80
function suite(title, fn);
81
function test(title, fn);
82
function setup(fn);
83
function teardown(fn);
84
function suiteSetup(fn);
85
function suiteTeardown(fn);
86
```
87
88
[Test Organization and Interfaces](./interfaces.md)
89
90
### Test Execution and Runner
91
92
Core test execution functionality with lifecycle management, event emission, and parallel execution support.
93
94
```javascript { .api }
95
class Mocha {
96
constructor(options);
97
run(callback);
98
addFile(filepath);
99
reporter(name, options);
100
timeout(ms);
101
slow(ms);
102
}
103
104
class Runner extends EventEmitter {
105
run(callback);
106
abort();
107
grep(pattern);
108
}
109
```
110
111
[Test Execution and Runner](./execution.md)
112
113
### Reporters and Output
114
115
Comprehensive reporting system with built-in reporters and support for custom reporters.
116
117
```javascript { .api }
118
class Base {
119
constructor(runner, options);
120
done(failures, callback);
121
epilogue();
122
}
123
```
124
125
[Reporters and Output](./reporters.md)
126
127
### Browser Support
128
129
Browser-specific functionality and setup for running tests in browser environments.
130
131
```javascript { .api }
132
// Browser global functions
133
mocha.setup(options);
134
mocha.run(callback);
135
mocha.throwError(error);
136
```
137
138
[Browser Support](./browser.md)
139
140
### CLI and Configuration
141
142
Command-line interface and configuration options for test execution.
143
144
```javascript { .api }
145
interface MochaOptions {
146
ui?: string;
147
reporter?: string;
148
timeout?: number;
149
slow?: number;
150
grep?: string | RegExp;
151
fgrep?: string;
152
bail?: boolean;
153
parallel?: boolean;
154
jobs?: number;
155
}
156
```
157
158
[CLI and Configuration](./cli-config.md)
159
160
## Types
161
162
```javascript { .api }
163
interface MochaOptions {
164
ui?: string;
165
reporter?: string | Reporter;
166
timeout?: number;
167
slow?: number;
168
grep?: string | RegExp;
169
fgrep?: string;
170
bail?: boolean;
171
parallel?: boolean;
172
jobs?: number;
173
asyncOnly?: boolean;
174
allowUncaught?: boolean;
175
checkLeaks?: boolean;
176
color?: boolean;
177
delay?: boolean;
178
diff?: boolean;
179
dryRun?: boolean;
180
fullTrace?: boolean;
181
inlineDiffs?: boolean;
182
invert?: boolean;
183
retries?: number;
184
forbidOnly?: boolean;
185
forbidPending?: boolean;
186
global?: string[];
187
recursive?: boolean;
188
sort?: boolean;
189
exit?: boolean;
190
}
191
192
interface Suite {
193
title: string;
194
parent: Suite | null;
195
pending: boolean;
196
timeout(ms?: number): number | Suite;
197
slow(ms?: number): number | Suite;
198
bail(bail?: boolean): boolean | Suite;
199
}
200
201
interface Test {
202
title: string;
203
fn: Function;
204
parent: Suite;
205
pending: boolean;
206
state: 'failed' | 'passed' | 'pending';
207
timeout(ms?: number): number | Test;
208
slow(ms?: number): number | Test;
209
}
210
211
interface Hook {
212
title: string;
213
fn: Function;
214
parent: Suite;
215
type: 'before' | 'after' | 'beforeEach' | 'afterEach';
216
}
217
218
interface Context {
219
test?: Test;
220
currentTest?: Test;
221
timeout(ms?: number): number | Context;
222
slow(ms?: number): number | Context;
223
skip(): never;
224
retries(count?: number): number | Context;
225
}
226
227
type DoneCB = (error?: any) => void;
228
type AsyncTestFunction = () => Promise<any>;
229
type TestFunction = (done?: DoneCB) => void | Promise<any>;
230
231
interface Reporter {
232
new(runner: Runner, options?: any): Reporter;
233
}
234
```