0
# CLI Interface
1
2
Karma's command-line interface provides comprehensive tools for project initialization, test execution, and server management. Designed for both interactive development and CI/CD integration.
3
4
## Capabilities
5
6
### Commands
7
8
Karma provides several commands for different aspects of test management.
9
10
```javascript { .api }
11
// Available CLI commands
12
karma init [configFile] // Initialize new configuration file
13
karma start [configFile] // Start server and/or run tests
14
karma run [configFile] // Trigger test run on existing server
15
karma stop [configFile] // Stop running server
16
karma completion // Generate shell completion script
17
```
18
19
### Init Command
20
21
Interactive configuration file generator that detects project setup and installs required plugins.
22
23
```bash
24
karma init [configFile]
25
```
26
27
**Options:**
28
- `configFile` - Optional path for config file (default: karma.conf.js)
29
30
**Usage Examples:**
31
32
```bash
33
# Initialize with default name
34
karma init
35
36
# Initialize with custom name
37
karma init my-karma.conf.js
38
39
# Initialize in TypeScript
40
karma init karma.conf.ts
41
```
42
43
The init command will interactively ask about:
44
- Testing framework (Jasmine, Mocha, QUnit, etc.)
45
- Use of RequireJS
46
- Browser selection
47
- Source file patterns
48
- Test file patterns
49
- File watching preferences
50
51
### Start Command
52
53
Start Karma server and optionally run tests. Primary command for both development and CI scenarios.
54
55
```bash
56
karma start [configFile] [options]
57
```
58
59
**Key Options:**
60
```javascript { .api }
61
--port <number> // Server port (default: 9876)
62
--auto-watch / --no-auto-watch // Enable/disable file watching
63
--single-run / --no-single-run // Run once and exit vs continuous
64
--browsers <list> // Comma-separated browser list
65
--reporters <list> // Comma-separated reporter list
66
--log-level <level> // disable|error|warn|info|debug
67
--colors / --no-colors // Enable/disable colored output
68
--fail-on-empty-test-suite // Fail if no tests found
69
--fail-on-failing-test-suite // Fail on any test failures
70
--grep <pattern> // Filter tests by pattern
71
--coverage // Enable coverage reporting
72
--watch // Force enable file watching
73
--singleRun // Force single run mode
74
```
75
76
**Usage Examples:**
77
78
```bash
79
# Start with default config
80
karma start
81
82
# Start with custom config
83
karma start my.karma.conf.js
84
85
# Single run for CI
86
karma start --single-run --browsers Chrome
87
88
# Development mode with watching
89
karma start --auto-watch --browsers Chrome,Firefox
90
91
# With specific reporters
92
karma start --reporters progress,coverage --single-run
93
94
# Debug mode
95
karma start --log-level debug --browsers Chrome
96
97
# Custom port
98
karma start --port 8080
99
```
100
101
### Run Command
102
103
Trigger test execution on an already running Karma server. Useful for external build tools and IDEs.
104
105
```bash
106
karma run [configFile] [options]
107
```
108
109
**Options:**
110
```javascript { .api }
111
--port <number> // Server port to connect to
112
--hostname <string> // Server hostname
113
--help // Show help
114
--removed-files <list> // Files that were removed
115
--added-files <list> // Files that were added
116
--changed-files <list> // Files that were changed
117
--refresh // Force refresh file list
118
```
119
120
**Usage Examples:**
121
122
```bash
123
# Run tests on default server
124
karma run
125
126
# Run on custom port
127
karma run --port 8080
128
129
# Run with file change information
130
karma run --changed-files src/app.js,src/util.js
131
132
# Force file list refresh
133
karma run --refresh
134
```
135
136
### Stop Command
137
138
Stop a running Karma server gracefully.
139
140
```bash
141
karma stop [configFile] [options]
142
```
143
144
**Options:**
145
```javascript { .api }
146
--port <number> // Server port to stop
147
--hostname <string> // Server hostname
148
--log-level <level> // Log level for stop command
149
```
150
151
**Usage Examples:**
152
153
```bash
154
# Stop default server
155
karma stop
156
157
# Stop server on custom port
158
karma stop --port 8080
159
160
# Stop with specific config
161
karma stop my.karma.conf.js
162
```
163
164
### Completion Command
165
166
Generate shell completion scripts for bash and zsh.
167
168
```bash
169
karma completion
170
```
171
172
**Usage Examples:**
173
174
```bash
175
# Generate bash completion
176
karma completion >> ~/.bashrc
177
178
# Generate zsh completion
179
karma completion >> ~/.zshrc
180
181
# Or save to completion directory
182
karma completion > /usr/local/etc/bash_completion.d/karma
183
```
184
185
## Global Options
186
187
Options available across all commands:
188
189
```javascript { .api }
190
--help // Show command help
191
--version // Show Karma version
192
--config <file> // Configuration file path
193
--colors / --no-colors // Enable/disable colored output
194
--log-level <level> // Set logging level
195
```
196
197
## Configuration File Formats
198
199
Karma supports multiple configuration file formats:
200
201
```javascript { .api }
202
// Supported configuration files
203
karma.conf.js // JavaScript (most common)
204
karma.conf.ts // TypeScript (requires ts-node)
205
karma.conf.coffee // CoffeeScript (requires coffeescript)
206
karma.conf.ls // LiveScript (requires LiveScript)
207
.karmarc // JSON format
208
```
209
210
**Usage Examples:**
211
212
```bash
213
# JavaScript config
214
karma start karma.conf.js
215
216
# TypeScript config
217
karma start karma.conf.ts
218
219
# CoffeeScript config
220
karma start karma.conf.coffee
221
222
# JSON config
223
karma start .karmarc
224
```
225
226
## Environment Variables
227
228
Karma respects several environment variables for default configuration:
229
230
```javascript { .api }
231
PORT // Default server port
232
IP // Default hostname
233
LISTEN_ADDR // Default listen address
234
```
235
236
**Usage Examples:**
237
238
```bash
239
# Set default port
240
export PORT=8080
241
karma start
242
243
# Set default hostname
244
export IP=0.0.0.0
245
karma start
246
247
# Use in CI
248
PORT=9999 karma start --single-run
249
```
250
251
## Exit Codes
252
253
Karma CLI commands return specific exit codes for scripting and CI integration:
254
255
```javascript { .api }
256
0 // Success - all tests passed
257
1 // Failure - tests failed or error occurred
258
2 // Configuration error
259
```
260
261
**Usage Examples:**
262
263
```bash
264
# Check exit code in scripts
265
karma start --single-run
266
if [ $? -eq 0 ]; then
267
echo "Tests passed"
268
else
269
echo "Tests failed"
270
exit 1
271
fi
272
273
# Use in CI pipelines
274
karma start --single-run --browsers ChromeHeadless || exit 1
275
```
276
277
## Common Workflows
278
279
### Development Workflow
280
281
```bash
282
# Initial setup
283
karma init
284
npm install --save-dev karma-chrome-launcher karma-jasmine
285
286
# Start development server with watching
287
karma start --auto-watch --browsers Chrome
288
289
# In another terminal, trigger runs
290
karma run
291
```
292
293
### CI/CD Workflow
294
295
```bash
296
# Headless browser testing
297
karma start --single-run --browsers ChromeHeadless
298
299
# With coverage
300
karma start --single-run --browsers ChromeHeadless --reporters progress,coverage
301
302
# Multiple browsers
303
karma start --single-run --browsers Chrome,Firefox,Safari
304
```
305
306
### Debugging Workflow
307
308
```bash
309
# Debug mode with detailed logging
310
karma start --log-level debug --browsers Chrome
311
312
# Keep browser open for debugging
313
karma start --single-run=false --auto-watch=false --browsers Chrome
314
```