0
# Command Line Interface
1

2
The mocha-webpack CLI provides a command-line interface for running tests with webpack precompilation. It maintains compatibility with mocha's CLI options while adding webpack-specific functionality.
3

4
## Capabilities
5

6
### Basic Command Structure
7

8
```bash { .api }
9
mocha-webpack [options] [files...]
10
```
11

12
If no files are specified, defaults to `./test`.
13

14
### Basic Options
15

16
Core functionality for test execution and configuration.
17

18
```bash { .api }
19
# Show help information
20
--help, -h, -?
21

22
# Show version number
23
--version
24

25
# Specify test UI interface (default: bdd)
26
--ui, -u <interface>
27
# Valid interfaces: bdd, tdd, exports, qunit
28

29
# Watch files for changes and rerun tests
30
--watch, -w
31

32
# Set number of times to retry failed test cases
33
--retries <count>
34

35
# Path to webpack configuration file (default: webpack.config.js)
36
--webpack-config <path>
37

38
# Environment passed to webpack config when it's a function
39
--webpack-env <env>
40

41
# Path to mocha-webpack options file
42
--opts <path>
43
```
44

45
### Output Options
46

47
Control test output formatting and verbosity.
48

49
```bash { .api }
50
# Force enabling of colors
51
--colors, -c
52

53
# Suppress informational messages
54
--quiet, -q
55

56
# Force interactive mode (default: enabled in terminal)
57
--interactive
58

59
# Enable growl notification support
60
--growl, -G
61

62
# Specify the reporter to use (default: spec)
63
--reporter, -R <name>
64

65
# Reporter-specific options (format: k=v,k2=v2,...)
66
--reporter-options, -O <options>
67
```
68

69
### Advanced Options
70

71
Detailed test configuration and filtering options.
72

73
```bash { .api }
74
# Force all tests to take a callback (async) or return a promise
75
--async-only, -A
76

77
# Bail after first test failure
78
--bail, -b
79

80
# Only test files matching pattern (for directory entries)
81
--glob <pattern>
82

83
# Only run tests matching pattern
84
--grep, -g <pattern>
85

86
# Only run tests containing string
87
--fgrep, -f <string>
88

89
# Invert --grep and --fgrep matches
90
--invert, -i
91

92
# Require the given module before running tests
93
--require, -r <module>
94
# Can be used multiple times
95

96
# Include the given module in test bundle
97
--include <module>
98
# Can be used multiple times
99

100
# "Slow" test threshold in milliseconds (default: 75ms)
101
--slow, -s <ms>
102

103
# Set test-case timeout in milliseconds (default: 2000ms)
104
--timeout, -t <ms>
105

106
# Check for global variable leaks
107
--check-leaks
108

109
# Display the full stack trace
110
--full-trace
111

112
# Display actual/expected differences inline within each string
113
--inline-diffs
114

115
# Require a clean shutdown of the event loop
116
--exit
117

118
# Wait for async suite definition
119
--delay
120

121
# Include subdirectories when using directory as test entry
122
--recursive
123
```
124

125
## Usage Examples
126

127
### Basic Usage
128

129
```bash
130
# Run a single test file
131
mocha-webpack simple.test.js
132

133
# Run all tests matching a glob pattern
134
mocha-webpack "test/**/*.js"
135

136
# Run tests in a directory with specific pattern
137
mocha-webpack --glob "*.test.js" test
138

139
# Include subdirectories
140
mocha-webpack --recursive --glob "*.test.js" test
141
```
142

143
### Watch Mode
144

145
```bash
146
# Watch for changes and rerun tests
147
mocha-webpack --watch test
148

149
# Watch with specific webpack config
150
mocha-webpack --watch --webpack-config webpack.test.js test
151

152
# Watch with custom reporter
153
mocha-webpack --watch --reporter json test
154
```
155

156
### Filtering Tests
157

158
```bash
159
# Run only tests matching a pattern
160
mocha-webpack --grep "user.*login" test
161

162
# Run only tests containing specific string
163
mocha-webpack --fgrep "authentication" test
164

165
# Invert the filter (run tests NOT matching pattern)
166
mocha-webpack --grep "integration" --invert test
167
```
168

169
### Configuration
170

171
```bash
172
# Use custom webpack config
173
mocha-webpack --webpack-config webpack.test.js test
174

175
# Pass environment to webpack config function
176
mocha-webpack --webpack-config webpack.config.js --webpack-env test test
177

178
# Use options file
179
mocha-webpack --opts test/mocha-webpack.opts
180

181
# Require setup modules
182
mocha-webpack --require babel-register --require ./test/setup.js test
183

184
# Include modules in test bundle
185
mocha-webpack --include ./src/polyfills.js test
186
```
187

188
### Output Control
189

190
```bash
191
# Use specific reporter
192
mocha-webpack --reporter json test
193

194
# Reporter with options
195
mocha-webpack --reporter xunit --reporter-options output=results.xml test
196

197
# Quiet mode (suppress info messages)
198
mocha-webpack --quiet test
199

200
# Force colors even when not in TTY
201
mocha-webpack --colors test
202

203
# Enable growl notifications
204
mocha-webpack --growl test
205
```
206

207
### Advanced Configuration
208

209
```bash
210
# Set timeout for slow tests
211
mocha-webpack --timeout 10000 test
212

213
# Set slow test threshold
214
mocha-webpack --slow 200 test
215

216
# Retry failed tests
217
mocha-webpack --retries 3 test
218

219
# Bail on first failure
220
mocha-webpack --bail test
221

222
# Force async tests only
223
mocha-webpack --async-only test
224

225
# Use TDD interface instead of BDD
226
mocha-webpack --ui tdd test
227

228
# Enable full stack traces
229
mocha-webpack --full-trace test
230

231
# Check for global leaks
232
mocha-webpack --check-leaks test
233
```
234

235
## Configuration Files
236

237
### Webpack Configuration
238

239
By default, mocha-webpack looks for `webpack.config.js` in the current directory. You can specify a different file:
240

241
```bash
242
mocha-webpack --webpack-config custom-webpack.config.js test
243
```
244

245
If your webpack config is a function, you can pass an environment:
246

247
```bash
248
mocha-webpack --webpack-config webpack.config.js --webpack-env test test
249
```
250

251
### Options File
252

253
Use an options file to avoid repeating command-line arguments:
254

255
```bash
256
mocha-webpack --opts test/mocha-webpack.opts
257
```
258

259
Example options file content:
260
```
261
--webpack-config webpack.test.js
262
--require babel-register
263
--recursive
264
--timeout 5000
265
--reporter spec
266
test
267
```
268

269
## Exit Codes
270

271
- **0**: All tests passed
272
- **1**: Test failures occurred or build error
273
- **Number**: Number of failed tests (when using `--exit`)
274

275
## Environment Variables
276

277
Mocha-webpack respects standard environment variables:
278

279
- `NODE_ENV`: Node.js environment
280
- `FORCE_COLOR`: Force color output
281
- `NO_COLOR`: Disable color output
282

283
## Glob Patterns
284

285
When using glob patterns, remember to quote them to prevent shell expansion:
286

287
```bash
288
# Correct - quoted pattern
289
mocha-webpack "test/**/*.test.js"
290

291
# Incorrect - shell will expand the pattern
292
mocha-webpack test/**/*.test.js
293
```
294

295
## Integration Examples
296

297
### With npm scripts
298

299
```json
300
{
301
  "scripts": {
302
    "test": "mocha-webpack --webpack-config webpack.test.js test",
303
    "test:watch": "npm run test -- --watch",
304
    "test:coverage": "nyc npm run test"
305
  }
306
}
307
```
308

309
### With CI/CD
310

311
```bash
312
# Basic CI test command
313
mocha-webpack --reporter json --bail test > test-results.json
314

315
# With coverage and JUnit output
316
nyc --reporter lcov mocha-webpack --reporter xunit --reporter-options output=test-results.xml test
317
```