0
# Configuration Management
1

2
Global configuration system for managing log levels, masking patterns, and file output with support for per-logger customization and environment variable integration.
3

4
## Capabilities
5

6
### Log Levels Configuration
7

8
Configure log levels for multiple loggers at once and set a global default log level.
9

10
```typescript { .api }
11
/**
12
 * Configure log levels for multiple loggers and set global default
13
 * @param logLevels - Object mapping logger names to log levels (optional)
14
 * @param wdioLogLevel - Global default log level (optional, defaults to 'info')
15
 */
16
logger.setLogLevelsConfig(
17
  logLevels?: Record<string, LogLevelDesc>, 
18
  wdioLogLevel?: LogLevelDesc
19
): void;
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import logger from '@wdio/logger';
26

27
// Set global default and specific logger levels
28
logger.setLogLevelsConfig({
29
  'webdriver': 'debug',      // Show all webdriver logs
30
  'selenium': 'warn',        // Only warnings and errors for selenium
31
  'browser': 'info',         // Standard info level for browser
32
  'devtools': 'silent'       // Suppress devtools logs
33
}, 'info'); // Global default level
34

35
// Create loggers - they'll use the configured levels
36
const wdLog = logger('webdriver');     // Uses debug level
37
const seleniumLog = logger('selenium'); // Uses warn level
38
const appLog = logger('myApp');        // Uses global default (info)
39

40
// Works with logger name prefixes (sub-loggers inherit parent config)
41
logger.setLogLevelsConfig({
42
  'api': 'debug',           // All api:* loggers will use debug
43
  'api:cache': 'warn'       // But api:cache specifically uses warn
44
});
45

46
const apiLog = logger('api:request');    // Uses debug (inherits from 'api')
47
const cacheLog = logger('api:cache');    // Uses warn (specific config)
48
```
49

50
### Masking Patterns Configuration
51

52
Configure masking patterns globally or per-logger to obfuscate sensitive information in log output.
53

54
```typescript { .api }
55
/**
56
 * Set masking patterns for secure logging of sensitive data
57
 * @param pattern - Either a global pattern string or object mapping logger names to patterns
58
 */
59
logger.setMaskingPatterns(
60
  pattern: string | Record<string, string>
61
): void;
62
```
63

64
**Pattern Formats:**
65
- Plain regex: `--key=[^ ]*`
66
- With flags: `/--key=([^ ]*)/i`
67
- Multiple patterns: `--key=[^ ]*,--secret=[^ ]*`
68
- With capturing groups: `/--key=([^ ]*)/i` (only groups are masked)
69

70
**Usage Examples:**
71

72
```typescript
73
import logger from '@wdio/logger';
74

75
// Global masking patterns for all loggers
76
logger.setMaskingPatterns('/--key=([^ ]*)/i,/--secret=([^ ]*)/i,/token=([^ ]*)/');
77

78
const log = logger('auth');
79
log.info('Command: wdio --key=secretKey123 --token=abc123');
80
// Output: "Command: wdio --key=**MASKED** --token=**MASKED**"
81

82
// Per-logger masking patterns
83
logger.setMaskingPatterns({
84
  'database': '/password=([^ ]*)/i,/connectionString=([^ ]*)/i',
85
  'api': '/authorization:\\s*bearer\\s+([^ ]*)/i',
86
  'cache': '/redis_url=([^ ]*)/i'
87
});
88

89
const dbLog = logger('database');
90
const apiLog = logger('api');
91

92
dbLog.info('Connecting with password=mypass123');
93
// Output: "Connecting with password=**MASKED**"
94

95
apiLog.info('Headers: { authorization: Bearer token123 }');
96
// Output: "Headers: { authorization: Bearer **MASKED** }"
97
```
98

99
### Utility Functions
100

101
Additional configuration utilities for managing logger lifecycle and state.
102

103
```typescript { .api }
104
/**
105
 * Wait for log file buffer to be flushed
106
 * Prevents log loss when process exits quickly
107
 * @returns Promise that resolves when buffer is flushed
108
 */
109
logger.waitForBuffer(): Promise<void>;
110

111
/**
112
 * Clear and close the log file stream
113
 * Useful for cleanup or log rotation
114
 */
115
logger.clearLogger(): void;
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
import logger from '@wdio/logger';
122

123
// Ensure all logs are written before process exit
124
process.on('exit', async () => {
125
  await logger.waitForBuffer();
126
});
127

128
// Rotate or clear log files
129
async function rotateLogs() {
130
  await logger.waitForBuffer();  // Ensure current logs are written
131
  logger.clearLogger();          // Close current log file
132
  
133
  // Log file will be recreated on next log message if WDIO_LOG_PATH is set
134
  const log = logger('app');
135
  log.info('New log session started');
136
}
137

138
// Graceful shutdown with log flushing
139
async function shutdown() {
140
  const log = logger('shutdown');
141
  log.info('Application shutting down...');
142
  
143
  await logger.waitForBuffer();  // Wait for logs to be written
144
  process.exit(0);
145
}
146
```
147

148
## Environment Variables Integration
149

150
The configuration system integrates with environment variables for deployment flexibility:
151

152
```typescript { .api }
153
// Environment variables that affect configuration:
154
interface EnvironmentConfig {
155
  /** Default log level when not explicitly configured */
156
  WDIO_LOG_LEVEL?: LogLevelDesc;
157
  
158
  /** When set, changes default level to 'trace' for debugging */
159
  WDIO_DEBUG?: string;
160
  
161
  /** Path for log file output (creates file if specified) */
162
  WDIO_LOG_PATH?: string;
163
  
164
  /** Global masking patterns (comma-separated regex strings) */
165
  WDIO_LOG_MASKING_PATTERNS?: string;
166
}
167
```
168

169
**Usage Examples:**
170

171
```bash
172
# Set via environment variables
173
export WDIO_LOG_LEVEL=debug
174
export WDIO_LOG_PATH=/tmp/wdio.log
175
export WDIO_LOG_MASKING_PATTERNS='/--key=([^ ]*)/i,/password=([^ ]*)/i'
176

177
# Or inline with command
178
WDIO_DEBUG=1 WDIO_LOG_PATH=./test.log npm run test
179
```
180

181
```typescript
182
// Environment variables take precedence unless overridden
183
process.env.WDIO_LOG_LEVEL = 'debug';  // Sets global default
184

185
logger.setLogLevelsConfig({
186
  'specific': 'warn'  // Overrides global default for 'specific' logger
187
});
188
// 'specific' logger uses 'warn', others use 'debug' from env var
189
```
190

191
## Configuration Priority
192

193
Configuration values are applied in this priority order (highest to lowest):
194

195
1. **Direct method calls** (`setLevel()`, `setLogLevelsConfig()`)
196
2. **Environment variables** (`WDIO_LOG_LEVEL`, `WDIO_DEBUG`)
197
3. **Default values** ('info' level)
198

199
**Examples:**
200

201
```typescript
202
// Priority demonstration
203
process.env.WDIO_LOG_LEVEL = 'debug';        // Environment setting
204

205
logger.setLogLevelsConfig({}, 'warn');       // Method call overrides env
206
// Global level is now 'warn', not 'debug'
207

208
logger.setLogLevelsConfig({
209
  'api': 'error'                             // Specific override
210
});
211
// 'api' logger uses 'error', others use global 'warn'
212

213
logger.setLevel('api', 'trace');             // Direct override
214
// 'api' logger now uses 'trace' (highest priority)
215
```