0
# Watch Mode
1

2
WebdriverIO CLI's watch mode provides intelligent file watching for continuous test execution during development. It automatically detects changes in test files and configuration, running only affected tests for optimal development workflow.
3

4
## Capabilities
5

6
### Watcher Class
7

8
File watching system with intelligent change detection and test execution optimization.
9

10
```typescript { .api }
11
/**
12
 * File watcher for continuous test execution during development
13
 */
14
class Watcher {
15
  /**
16
   * Initialize watcher with configuration
17
   * @param configFile - Path to WebdriverIO configuration file
18
   * @param args - Command arguments excluding configPath
19
   */
20
  constructor(
21
    configFile: string,
22
    args: Omit<RunCommandArguments, 'configPath'>
23
  );
24

25
  /**
26
   * Start watching files for changes and execute tests automatically
27
   * Watches spec files and configuration files, automatically re-running tests on changes
28
   * @returns Promise that resolves when all test workers finish
29
   */
30
  watch(): Promise<void>;
31
}
32
```
33

34
### CLI Watch Mode
35

36
Enable watch mode through command-line interface for interactive development.
37

38
```bash { .api }
39
# Enable watch mode
40
wdio run wdio.conf.js --watch
41

42
# Watch mode with specific specs
43
wdio run wdio.conf.js --watch --spec ./test/specs/unit/**/*.js
44

45
# Watch mode with suite filtering
46
wdio run wdio.conf.js --watch --suite unit
47

48
# Watch mode with custom log level
49
wdio run wdio.conf.js --watch --logLevel debug
50
```
51

52
## Usage Examples
53

54
### Basic Watch Mode
55

56
```typescript
57
import { Watcher } from "@wdio/cli";
58

59
// Start basic watch mode
60
const watcher = new Watcher("./wdio.conf.js", {
61
  logLevel: "info"
62
});
63

64
await watcher.watch();
65
```
66

67
### Advanced Watch Configuration
68

69
```typescript
70
import { Watcher } from "@wdio/cli";
71

72
// Watch mode with custom options
73
const watcher = new Watcher("./wdio.conf.js", {
74
  spec: ["./test/specs/**/*.js"],
75
  logLevel: "debug",
76
  bail: 1,
77
  baseUrl: "http://localhost:3000"
78
});
79

80
// File watching is configured in wdio.conf.js via filesToWatch option
81
await watcher.watch();
82
```
83

84
### Development Workflow Integration
85

86
```typescript
87
import { Watcher } from "@wdio/cli";
88

89
class DevServer {
90
  private watcher: Watcher;
91

92
  async startDevelopment() {
93
    // Start development server
94
    await this.startServer();
95

96
    // Initialize test watcher
97
    this.watcher = new Watcher("./wdio.conf.js", {
98
      baseUrl: "http://localhost:3000",
99
      logLevel: "info",
100
      spec: ["./test/specs/integration/**/*.js"]
101
    });
102

103
    console.log("Starting watch mode...");
104
    await this.watcher.watch();
105
  }
106

107
  async stopDevelopment() {
108
    // Note: Watcher doesn't provide stop method, use process signals instead
109
    await this.stopServer();
110
  }
111

112
  private async startServer() {
113
    // Start your development server
114
  }
115

116
  private async stopServer() {
117
    // Stop your development server
118
  }
119
}
120
```
121

122
## Watch Mode Features
123

124
### Intelligent Change Detection
125

126
Watch mode automatically detects and responds to various types of file changes:
127

128
```typescript
129
// Configuration changes trigger full test suite reload
130
// wdio.conf.js, wdio.*.conf.js
131

132
// Test file changes trigger affected spec execution
133
// ./test/specs/**/*.js, ./test/**/*.spec.js
134

135
// Source file changes trigger related test execution
136
// ./src/**/*.js (runs tests that import changed files)
137

138
// Package.json changes trigger dependency reload
139
// package.json, package-lock.json, yarn.lock
140
```
141

142
### File Pattern Matching
143

144
File watching patterns are configured in your WebdriverIO configuration file using the `filesToWatch` option:
145

146
```javascript
147
// wdio.conf.js
148
export const config = {
149
  // ... other config options
150
  
151
  // Files to watch for changes (in addition to spec files)
152
  filesToWatch: [
153
    // JavaScript/TypeScript files
154
    "./src/**/*.{js,ts,jsx,tsx}",
155
    
156
    // Configuration files
157
    "./*.conf.{js,ts,json}",
158
    
159
    // Static assets that affect tests
160
    "./public/**/*.{html,css,json}",
161
    
162
    // Environment files
163
    "./.env*"
164
  ]
165
};
166
```
167

168
### Interactive Commands
169

170
During watch mode, the following interactive commands are available:
171

172
```bash
173
# Watch mode runs automatically on file changes
174
# Use Ctrl+C to quit watch mode
175
# Manual test triggering is handled through configuration changes
176
```
177

178
### Programmatic Control
179

180
```typescript
181
import { Watcher } from "@wdio/cli";
182

183
const watcher = new Watcher("./wdio.conf.js", {
184
  logLevel: "info"
185
});
186

187
// Handle process termination
188
process.on('SIGINT', () => {
189
  console.log('Stopping watch mode...');
190
  process.exit(0);
191
});
192

193
process.on('SIGTERM', () => {
194
  console.log('Stopping watch mode...');
195
  process.exit(0);
196
});
197

198
await watcher.watch();
199
```
200

201
## Performance Optimization
202

203
### Selective Test Execution
204

205
```typescript
206
import { Watcher } from "@wdio/cli";
207

208
// Watch mode with performance optimizations
209
const watcher = new Watcher("./wdio.conf.js", {
210
  // Only run specific suites to reduce execution time
211
  suite: ["unit", "integration"],
212
  
213
  // Use bail to stop on first failure
214
  bail: 1,
215
  
216
  // Reduce parallel instances for faster startup
217
  maxInstances: 2,
218
  
219
  // Minimize logging for better performance
220
  logLevel: "warn"
221
});
222
```
223

224
### Debouncing and Throttling
225

226
```typescript
227
// Watch mode automatically implements debouncing
228
// Multiple rapid file changes are batched into single test run
229
// Default debounce delay: 300ms
230

231
// Watcher automatically implements debouncing internally
232
// Multiple rapid file changes are batched into single test run
233
// Default debounce delay: approximately 300ms
234
```
235

236
## Integration Patterns
237

238
### IDE Integration
239

240
```typescript
241
// VSCode task configuration (.vscode/tasks.json)
242
{
243
  "version": "2.0.0",
244
  "tasks": [
245
    {
246
      "label": "WebdriverIO Watch",
247
      "type": "shell",
248
      "command": "npx wdio run wdio.conf.js --watch",
249
      "group": "test",
250
      "presentation": {
251
        "echo": true,
252
        "reveal": "always",
253
        "focus": false,
254
        "panel": "shared"
255
      },
256
      "problemMatcher": [],
257
      "runOptions": {
258
        "runOn": "folderOpen"
259
      }
260
    }
261
  ]
262
}
263
```
264

265
### Docker Development
266

267
```typescript
268
// Docker development setup with watch mode
269
import { Watcher } from "@wdio/cli";
270

271
class DockerDevEnvironment {
272
  private watcher: Watcher;
273

274
  async startContainer() {
275
    // Start Docker container with volume mounts
276
    // docker run -v $(pwd):/app -p 4444:4444 selenium/standalone-chrome
277
    
278
    this.watcher = new Watcher("./wdio.docker.conf.js", {
279
      hostname: "localhost",
280
      port: 4444,
281
      baseUrl: "http://host.docker.internal:3000"
282
    });
283

284
    await this.watcher.watch();
285
  }
286
}
287
```
288

289
### CI/CD Integration
290

291
```typescript
292
// Conditional watch mode for different environments
293
const isCI = process.env.CI === 'true';
294
const isDevelopment = process.env.NODE_ENV === 'development';
295

296
if (isDevelopment && !isCI) {
297
  // Enable watch mode in development
298
  const watcher = new Watcher("./wdio.conf.js", {
299
    logLevel: "debug"
300
  });
301
  
302
  await watcher.watch();
303
} else {
304
  // Regular test execution in CI
305
  const launcher = new Launcher("./wdio.conf.js", {
306
    logLevel: "warn",
307
    bail: 1
308
  });
309
  
310
  const exitCode = await launcher.run();
311
  process.exit(exitCode);
312
}
313
```
314

315
## Troubleshooting
316

317
### Common Watch Mode Issues
318

319
```javascript
320
// Issue: Watch mode not detecting file changes
321
// Solution: Configure filesToWatch in wdio.conf.js
322

323
// wdio.conf.js
324
export const config = {
325
  // Ensure spec files are correctly configured
326
  specs: ['./test/**/*.js'],
327
  
328
  // Add additional files to watch
329
  filesToWatch: [
330
    "./src/**/*.js",     // Watch source files
331
    "./wdio.*.conf.js"   // Watch configuration files
332
  ]
333
};
334

335
// Issue: Too many files being watched (performance impact)
336
// Solution: Use more specific patterns
337

338
export const config = {
339
  filesToWatch: [
340
    // More specific (recommended)
341
    "./src/**/*.js",
342
    "./test/**/*.js",
343
    "./config/**/*.js"
344
  ]
345
};
346

347
// Issue: Watch mode consuming too much memory
348
// Solution: Use specific patterns and avoid broad globs
349

350
export const config = {
351
  filesToWatch: [
352
    "./src/**/*.js",
353
    "./test/**/*.js",
354
    // Chokidar automatically excludes node_modules by default
355
    // Use specific patterns to avoid watching too many files
356
  ]
357
};
358
```