0
# Programmatic API
1

2
The programmatic API provides a fluent interface for configuring and running tests in Node.js applications. It centers around the MochaWebpack class, which offers chainable methods for configuration.
3

4
## Capabilities
5

6
### Factory Function
7

8
Creates a new MochaWebpack instance with default configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new MochaWebpack instance
13
 * @returns {MochaWebpack} New MochaWebpack instance with default options
14
 */
15
function createMochaWebpack(): MochaWebpack;
16
```
17

18
**Usage Example:**
19

20
```javascript
21
const createMochaWebpack = require('mocha-webpack');
22

23
const mochaWebpack = createMochaWebpack();
24
```
25

26
### Test Entry Management
27

28
Add test files and included modules to be processed by webpack.
29

30
```javascript { .api }
31
/**
32
 * Add file to run tests against
33
 * @param {string} file - File path or glob pattern
34
 * @returns {MochaWebpack} MochaWebpack instance for chaining
35
 */
36
addEntry(file: string): MochaWebpack;
37

38
/**
39
 * Add file to include in the test bundle
40
 * @param {string} file - Absolute path to module
41
 * @returns {MochaWebpack} MochaWebpack instance for chaining
42
 */
43
addInclude(file: string): MochaWebpack;
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
mochaWebpack
50
  .addEntry('./test/**/*.test.js')
51
  .addEntry('./test/specific.test.js')
52
  .addInclude('/path/to/setup-file.js');
53
```
54

55
### Configuration Methods
56

57
Configure the working directory and webpack settings.
58

59
```javascript { .api }
60
/**
61
 * Set the current working directory
62
 * @param {string} cwd - Absolute working directory path
63
 * @returns {MochaWebpack} MochaWebpack instance for chaining
64
 */
65
cwd(cwd: string): MochaWebpack;
66

67
/**
68
 * Set webpack configuration
69
 * @param {object} config - Webpack configuration object
70
 * @returns {MochaWebpack} MochaWebpack instance for chaining
71
 */
72
webpackConfig(config: object): MochaWebpack;
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
mochaWebpack
79
  .cwd(process.cwd())
80
  .webpackConfig({
81
    mode: 'development',
82
    resolve: {
83
      extensions: ['.js', '.ts']
84
    }
85
  });
86
```
87

88
### Test Execution Control
89

90
Control test execution behavior including bail, timeouts, and retries.
91

92
```javascript { .api }
93
/**
94
 * Enable or disable bailing on the first test failure
95
 * @param {boolean} bail - Whether to bail on first failure (default: false)
96
 * @returns {MochaWebpack} MochaWebpack instance for chaining
97
 */
98
bail(bail?: boolean): MochaWebpack;
99

100
/**
101
 * Set test timeout in milliseconds
102
 * @param {number} timeout - Timeout in milliseconds (0 disables timeout)
103
 * @returns {MochaWebpack} MochaWebpack instance for chaining
104
 */
105
timeout(timeout: number): MochaWebpack;
106

107
/**
108
 * Set number of times to retry failed tests
109
 * @param {number} count - Number of retries
110
 * @returns {MochaWebpack} MochaWebpack instance for chaining
111
 */
112
retries(count: number): MochaWebpack;
113

114
/**
115
 * Set slowness threshold in milliseconds
116
 * @param {number} threshold - Slow test threshold in milliseconds
117
 * @returns {MochaWebpack} MochaWebpack instance for chaining
118
 */
119
slow(threshold: number): MochaWebpack;
120
```
121

122
### Test Interface and Reporting
123

124
Configure test interface, reporters, and output formatting.
125

126
```javascript { .api }
127
/**
128
 * Set test UI interface
129
 * @param {string} ui - Interface type: 'bdd', 'tdd', 'exports', 'qunit'
130
 * @returns {MochaWebpack} MochaWebpack instance for chaining
131
 */
132
ui(ui: string): MochaWebpack;
133

134
/**
135
 * Set test reporter and options
136
 * @param {string|Function} reporter - Reporter name or constructor
137
 * @param {object} reporterOptions - Reporter-specific options
138
 * @returns {MochaWebpack} MochaWebpack instance for chaining
139
 */
140
reporter(reporter: string | Function, reporterOptions: object): MochaWebpack;
141

142
/**
143
 * Force color output
144
 * @param {boolean} colors - Whether to use colors
145
 * @returns {MochaWebpack} MochaWebpack instance for chaining
146
 */
147
useColors(colors: boolean): MochaWebpack;
148

149
/**
150
 * Use inline diffs instead of +/-
151
 * @param {boolean} inlineDiffs - Whether to use inline diffs
152
 * @returns {MochaWebpack} MochaWebpack instance for chaining
153
 */
154
useInlineDiffs(inlineDiffs: boolean): MochaWebpack;
155

156
/**
157
 * Suppress informational messages
158
 * @returns {MochaWebpack} MochaWebpack instance for chaining
159
 */
160
quiet(): MochaWebpack;
161
```
162

163
### Test Filtering
164

165
Filter which tests to run based on patterns or strings.
166

167
```javascript { .api }
168
/**
169
 * Only run tests containing the specified string
170
 * @param {string} str - String to search for in test names
171
 * @returns {MochaWebpack} MochaWebpack instance for chaining
172
 */
173
fgrep(str: string): MochaWebpack;
174

175
/**
176
 * Only run tests matching the specified pattern
177
 * @param {string|RegExp} pattern - Regular expression or string pattern
178
 * @returns {MochaWebpack} MochaWebpack instance for chaining
179
 */
180
grep(pattern: string | RegExp): MochaWebpack;
181

182
/**
183
 * Invert grep and fgrep matches
184
 * @returns {MochaWebpack} MochaWebpack instance for chaining
185
 */
186
invert(): MochaWebpack;
187
```
188

189
### Advanced Options
190

191
Additional configuration options for specialized testing scenarios.
192

193
```javascript { .api }
194
/**
195
 * Ignore global variable leaks
196
 * @param {boolean} ignore - Whether to ignore leaks
197
 * @returns {MochaWebpack} MochaWebpack instance for chaining
198
 */
199
ignoreLeaks(ignore: boolean): MochaWebpack;
200

201
/**
202
 * Display full stack traces on failing tests
203
 * @returns {MochaWebpack} MochaWebpack instance for chaining
204
 */
205
fullStackTrace(): MochaWebpack;
206

207
/**
208
 * Force all tests to be async (accepting a callback)
209
 * @returns {MochaWebpack} MochaWebpack instance for chaining
210
 */
211
asyncOnly(): MochaWebpack;
212

213
/**
214
 * Delay root suite execution
215
 * @returns {MochaWebpack} MochaWebpack instance for chaining
216
 */
217
delay(): MochaWebpack;
218

219
/**
220
 * Force interactive mode
221
 * @param {boolean} interactive - Whether to use interactive mode
222
 * @returns {MochaWebpack} MochaWebpack instance for chaining
223
 */
224
interactive(interactive: boolean): MochaWebpack;
225

226
/**
227
 * Enable growl notification support
228
 * @returns {MochaWebpack} MochaWebpack instance for chaining
229
 */
230
growl(): MochaWebpack;
231
```
232

233
### Test Execution
234

235
Execute tests either once or in watch mode.
236

237
```javascript { .api }
238
/**
239
 * Run tests once
240
 * @returns {Promise<number>} Promise resolving to number of failed tests
241
 * @throws {Error} Build errors during webpack compilation
242
 */
243
run(): Promise<number>;
244

245
/**
246
 * Run tests and watch for file changes
247
 * @returns {Promise<void>} Promise that resolves when watch mode ends
248
 * @description Automatically reruns affected tests when files change
249
 */
250
watch(): Promise<void>;
251
```
252

253
**Usage Examples:**
254

255
```javascript
256
// Run tests once
257
mochaWebpack
258
  .addEntry('./test/**/*.test.js')
259
  .webpackConfig(webpackConfig)
260
  .run()
261
  .then((failures) => {
262
    console.log(\`Tests completed with \${failures} failures\`);
263
    process.exit(failures);
264
  })
265
  .catch((err) => {
266
    console.error('Build failed:', err);
267
    process.exit(1);
268
  });
269

270
// Watch mode
271
mochaWebpack
272
  .addEntry('./test/**/*.test.js')
273
  .webpackConfig(webpackConfig)
274
  .watch()
275
  .catch((err) => {
276
    console.error('Watch mode failed:', err);
277
    process.exit(1);
278
  });
279
```
280

281
## Properties
282

283
```javascript { .api }
284
/**
285
 * Current test entries (files/globs to test)
286
 */
287
entries: string[];
288

289
/**
290
 * Files to include in the test bundle
291
 */
292
includes: string[];
293

294
/**
295
 * Current configuration options
296
 */
297
options: MochaWebpackOptions;
298
```
299

300
## Complete Example
301

302
```javascript
303
const createMochaWebpack = require('mocha-webpack');
304
const webpackConfig = require('./webpack.config.js');
305

306
const mochaWebpack = createMochaWebpack();
307

308
mochaWebpack
309
  // Add test files
310
  .addEntry('./test/**/*.test.js')
311
  .addInclude('./test/setup.js')
312
  
313
  // Configure webpack
314
  .webpackConfig(webpackConfig)
315
  
316
  // Configure mocha
317
  .ui('bdd')
318
  .reporter('spec')
319
  .timeout(5000)
320
  .bail(true)
321
  
322
  // Configure filtering
323
  .grep('integration')
324
  
325
  // Configure output
326
  .useColors(true)
327
  .quiet()
328
  
329
  // Run tests
330
  .run()
331
  .then((failures) => {
332
    process.exit(failures);
333
  })
334
  .catch((err) => {
335
    console.error(err);
336
    process.exit(1);
337
  });
338
```