0
# CLI Interface
1

2
Command-line interface for running tests in Node.js environments with extensive configuration options, built-in reporters, and watch mode support.
3

4
## Capabilities
5

6
### Basic CLI Usage
7

8
Run QUnit tests from the command line.
9

10
```bash { .api }
11
# Basic usage
12
qunit [options] [files...]
13

14
# Run all tests in test directory
15
qunit test/
16

17
# Run specific test files
18
qunit test/unit/math.js test/unit/string.js
19

20
# Run tests with glob patterns
21
qunit "test/**/*.js"
22
```
23

24
**Usage Examples:**
25

26
```bash
27
# Run all JavaScript files in test directory
28
qunit test/
29

30
# Run specific test file
31
qunit test/unit/calculator.js
32

33
# Run multiple test files
34
qunit test/unit/*.js test/integration/*.js
35

36
# Run with glob pattern
37
qunit "test/**/*-test.js"
38
```
39

40
### CLI Options
41

42
Configure test execution through command-line options.
43

44
```bash { .api }
45
# Available CLI options (based on actual implementation)
46
-f, --filter <filter>       # Filter tests by pattern
47
-m, --module <name>         # Run only specified module  
48
-r, --reporter [name]       # Specify reporter; list available if no name
49
--require <module>          # Require module before tests (can be repeated)
50
--seed <value>              # Set randomization seed (or 'true' for random)
51
-w, --watch                 # Watch files for changes and re-run tests
52
```
53

54
**Usage Examples:**
55

56
```bash
57
# Filter tests by name pattern
58
qunit --filter "user" test/
59

60
# Run only specific module
61
qunit --module "Authentication" test/
62

63
# List available reporters
64
qunit --reporter
65

66
# Use specific reporter (if available)
67
qunit --reporter console test/
68

69
# Watch for file changes
70
qunit --watch test/
71

72
# Require setup module (can be used multiple times)
73
qunit --require ./test/setup.js --require babel-register test/
74

75
# Set randomization seed
76
qunit --seed 12345 test/
77

78
# Generate random seed
79
qunit --seed true test/
80
```
81

82
### Programmatic CLI Usage
83

84
Use QUnit CLI programmatically in Node.js scripts.
85

86
```javascript { .api }
87
/**
88
 * Run QUnit tests programmatically
89
 * @param {string[]} files - Array of file patterns
90
 * @param {Object} options - CLI configuration options
91
 * @param {string} [options.filter] - Filter tests by pattern
92
 * @param {string} [options.module] - Run only specified module
93
 * @param {string} [options.reporter] - Specify reporter
94
 * @param {string[]} [options.requires] - Modules to require before tests
95
 * @param {string} [options.seed] - Randomization seed
96
 */
97
const run = require('../src/cli/run');
98

99
/**
100
 * Run QUnit tests in watch mode
101
 * @param {string[]} files - Array of file patterns
102
 * @param {Object} options - CLI configuration options
103
 */
104
run.watch(files, options);
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
const run = require('qunit/src/cli/run');
111

112
// Run tests programmatically
113
run(['test/**/*.js'], {
114
  filter: 'integration',
115
  reporter: 'tap',
116
  seed: '12345'
117
});
118

119
// Run in watch mode
120
run.watch(['test/**/*.js'], {
121
  filter: 'unit',
122
  requires: ['./test/setup.js']
123
});
124
```
125

126
### File Pattern Matching
127

128
Specify test files using various patterns.
129

130
```bash { .api }
131
# Directory patterns
132
qunit test/                 # All files in directory
133
qunit test/ lib/           # Multiple directories
134

135
# File extension patterns  
136
qunit test/*.js            # All .js files
137
qunit test/*.{js,ts}       # Multiple extensions
138

139
# Glob patterns
140
qunit "test/**/*.js"       # Recursive glob
141
qunit "test/**/test-*.js"  # Pattern matching
142

143
# Specific files
144
qunit test/unit/math.js test/unit/string.js
145
```
146

147
**Usage Examples:**
148

149
```bash
150
# Run all test files recursively
151
qunit "test/**/*.js"
152

153
# Run only unit tests
154
qunit "test/unit/**/*.js"
155

156
# Run tests with specific naming pattern
157
qunit "test/**/*-test.js" "test/**/*.test.js"
158

159
# Mix directories and patterns
160
qunit test/unit/ "test/integration/**/*.js"
161
```
162

163
### Built-in Reporters
164

165
Use different output formats for test results.
166

167
```bash { .api }
168
# List available reporters
169
qunit --reporter
170

171
# The actual available reporters depend on the implementation
172
# Check source code or run qunit --reporter to see what's available
173

174
# Custom reporter (via require)
175
qunit --require ./custom-reporter.js test/
176
```
177

178
**Default Console Output:**
179

180
```
181
TAP version 13
182
1..3
183
ok 1 Math > addition
184
ok 2 Math > subtraction  
185
not ok 3 String > concatenation
186
  ---
187
  message: strings should be concatenated
188
  severity: fail
189
  actual: helloworld
190
  expected: hello world
191
  ...
192
# pass 2
193
# skip 0
194
# todo 0
195
# fail 1
196
```
197

198
**With Reporter Option:**
199

200
The actual output format depends on which reporters are available. Use `qunit --reporter` to list available options.
201

202
### Watch Mode
203

204
Automatically re-run tests when files change.
205

206
```bash { .api }
207
# Enable watch mode
208
qunit --watch test/
209

210
# Watch with specific patterns
211
qunit --watch "test/**/*.js" "src/**/*.js"
212

213
# Watch with custom reporter
214
qunit --watch --reporter tap test/
215
```
216

217
**Usage Examples:**
218

219
```bash
220
# Basic watch mode
221
qunit --watch test/
222

223
# Watch source and test files
224
qunit --watch test/ src/
225

226
# Watch with filtering
227
qunit --watch --filter "unit" test/
228

229
# Watch with custom options
230
qunit --watch --reporter console --verbose test/
231
```
232

233
### Module Requirements
234

235
Load modules before running tests.
236

237
```bash { .api }
238
# Require single module
239
qunit --require ./test/setup.js test/
240

241
# Require multiple modules
242
qunit --require ./test/setup.js --require babel-register test/
243

244
# Require with environment setup
245
qunit --require dotenv/config --require ./test/globals.js test/
246
```
247

248
**Setup Module Example:**
249

250
```javascript
251
// test/setup.js
252
const { JSDOM } = require('jsdom');
253

254
// Setup DOM environment for browser-like tests
255
const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
256
global.window = dom.window;
257
global.document = dom.window.document;
258
global.navigator = dom.window.navigator;
259

260
// Setup global test utilities
261
global.testHelpers = {
262
  createUser: (name) => ({ id: Math.random(), name }),
263
  mockFetch: () => { /* mock implementation */ }
264
};
265

266
console.log('Test environment initialized');
267
```
268

269
### Exit Codes
270

271
QUnit CLI returns standard exit codes for CI/CD integration.
272

273
```bash { .api }
274
# Exit codes (standard convention)
275
0  # All tests passed
276
1  # One or more tests failed or other error
277
```
278

279
**Usage Examples:**
280

281
```bash
282
#!/bin/bash
283
# CI script example
284

285
# Run tests and capture exit code
286
qunit test/
287
EXIT_CODE=$?
288

289
if [ $EXIT_CODE -eq 0 ]; then
290
  echo "All tests passed! ✅"
291
  npm run build
292
elif [ $EXIT_CODE -eq 1 ]; then
293
  echo "Tests failed! ❌"
294
  exit 1
295
else
296
  echo "Test runner error (exit code: $EXIT_CODE)"
297
  exit $EXIT_CODE
298
fi
299
```
300

301
### Environment Integration
302

303
Integrate with different Node.js environments and tools.
304

305
```bash { .api }
306
# With environment variables
307
NODE_ENV=test qunit test/
308

309
# With ES modules support
310
qunit --require esm test/**/*.mjs
311

312
# With TypeScript
313
qunit --require ts-node/register test/**/*.ts
314

315
# With Babel
316
qunit --require @babel/register test/
317
```
318

319
**Package.json Integration:**
320

321
```json
322
{
323
  "scripts": {
324
    "test": "qunit test/",
325
    "test:watch": "qunit --watch test/",
326
    "test:unit": "qunit --filter unit test/",
327
    "test:integration": "qunit --filter integration test/",
328
    "test:ci": "qunit --reporter tap test/ > test-results.tap"
329
  }
330
}
331
```
332

333
### Default File Pattern
334

335
When no files are specified, QUnit uses a default pattern.
336

337
```bash { .api }
338
# Default pattern when no files specified
339
qunit  # Equivalent to: qunit 'test/**/*.{js,mjs,cjs}'
340
```
341

342
**File Pattern Notes:**
343
- Defaults to `'test/**/*.{js,mjs,cjs}'` when no files specified
344
- Supports glob patterns for flexible file selection
345
- Can specify multiple patterns and individual files
346

347
## CLI Implementation Details
348

349
```javascript { .api }
350
/**
351
 * CLI options based on actual implementation (bin/qunit.js)
352
 * @typedef {Object} CLIOptions
353
 * @property {string} [filter] - Filter tests by pattern (-f, --filter)
354
 * @property {string} [module] - Run only specified module (-m, --module)
355
 * @property {string|boolean} [reporter] - Specify reporter (-r, --reporter)
356
 * @property {string[]} [requires] - Modules to require (--require, can be repeated)
357
 * @property {string} [seed] - Randomization seed (--seed)
358
 * @property {boolean} [watch] - Watch mode (-w, --watch)
359
 */
360

361
/**
362
 * The CLI is built using Commander.js and accepts:
363
 * - File arguments: Array of files/patterns to test
364
 * - Options: Filter, module, reporter, require, seed, watch
365
 * - Default pattern: 'test/**/*.{js,mjs,cjs}' when no files specified
366
 */
367
```
368

369
## Getting Help
370

371
```bash { .api }
372
# Show CLI help
373
qunit --help
374

375
# Show version
376
qunit --version
377

378
# List available reporters
379
qunit --reporter
380
```