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