0
# Core Logging
1

2
Standard logging functionality with enhanced WebdriverIO-specific features including colorized output, prefixed messages, file logging support, and custom progress logging.
3

4
## Capabilities
5

6
### Logger Factory Function
7

8
Creates or retrieves a logger instance for a specified component name. Each logger instance maintains its own configuration and state.
9

10
```typescript { .api }
11
/**
12
 * Creates or retrieves a logger instance for a specified component name
13
 * @param name - The name/identifier for the logger (e.g., 'myPackage', 'webdriver:chrome')
14
 * @returns Logger instance with all standard and custom logging methods
15
 */
16
function getLogger(name: string): Logger;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import logger from '@wdio/logger';
23

24
// Create loggers for different components
25
const mainLog = logger('myApp');
26
const dbLog = logger('database');
27
const apiLog = logger('api');
28

29
// Each logger can have different settings
30
logger.setLevel('database', 'debug');
31
logger.setLevel('api', 'warn');
32
```
33

34
### Logger Instance Methods
35

36
Each logger instance provides all standard log levels plus the custom progress method.
37

38
```typescript { .api }
39
interface Logger {
40
  /**
41
   * Log trace-level messages (level 0)
42
   * @param args - Messages and objects to log
43
   */
44
  trace(...args: any[]): void;
45

46
  /**
47
   * Log debug-level messages (level 1)
48
   * @param args - Messages and objects to log
49
   */
50
  debug(...args: any[]): void;
51

52
  /**
53
   * Log info-level messages (level 2)
54
   * @param args - Messages and objects to log
55
   */
56
  info(...args: any[]): void;
57

58
  /**
59
   * Log warning messages (level 3)
60
   * @param args - Messages and objects to log
61
   */
62
  warn(...args: any[]): void;
63

64
  /**
65
   * Log error messages (level 4)
66
   * @param args - Messages and objects to log
67
   */
68
  error(...args: any[]): void;
69

70
  /**
71
   * Custom progress logging for dynamic terminal updates
72
   * Writes directly to process.stdout with cursor manipulation
73
   * @param msg - Progress message strings
74
   */
75
  progress(...msg: string[]): void;
76

77
  /**
78
   * Set the minimum log level for this logger instance
79
   * @param level - Log level descriptor
80
   */
81
  setLevel(level: LogLevelDesc): void;
82

83
  /**
84
   * Get the current log level number for this logger
85
   * @returns Current log level as number (0-5)
86
   */
87
  getLevel(): LogLevelNumbers;
88

89
  /** Array of regex patterns for masking sensitive data in this logger's output */
90
  maskingPatterns: RegExp[] | undefined;
91
}
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
import logger from '@wdio/logger';
98

99
const log = logger('myService');
100

101
// Standard logging
102
log.trace('Detailed execution trace');
103
log.debug('Debug information');
104
log.info('General information');
105
log.warn('Warning message');
106
log.error('Error occurred', { errorCode: 500 });
107

108
// Progress logging for dynamic updates
109
const total = 100;
110
for (let i = 0; i <= total; i += 10) {
111
  log.progress(`Downloading... ${i}%`);
112
  await new Promise(resolve => setTimeout(resolve, 100));
113
}
114
log.progress(''); // Clear progress line
115

116
// Error object logging (automatically displays stack trace)
117
try {
118
  throw new Error('Something went wrong');
119
} catch (error) {
120
  log.error('Operation failed:', error);
121
}
122
```
123

124
### Progress Logging
125

126
Special logging method for dynamic terminal updates, particularly useful for showing download progress, processing status, or other real-time information.
127

128
```typescript { .api }
129
/**
130
 * Special logging method for dynamic terminal updates
131
 * Equivalent to info level but writes directly to stdout with cursor manipulation
132
 * Only displays in TTY environments and when log level <= info
133
 * @param data - Progress message strings
134
 */
135
progress(...data: string[]): void;
136
```
137

138
**Key Features:**
139
- Writes directly to `process.stdout` (not captured in log files)
140
- Only works in TTY environments
141
- Respects log level (suppressed if level > info)
142
- Uses cursor manipulation to overwrite previous progress messages
143
- Must call with empty string to clear the progress line
144

145
**Usage Examples:**
146

147
```typescript
148
import logger from '@wdio/logger';
149

150
const log = logger('downloader');
151

152
// Show download progress
153
let downloaded = 0;
154
const total = 1000;
155

156
const interval = setInterval(() => {
157
  downloaded += 100;
158
  const percent = Math.round((downloaded / total) * 100);
159
  log.progress(`Downloading driver... ${percent}%`);
160
  
161
  if (downloaded >= total) {
162
    clearInterval(interval);
163
    log.progress(''); // Clear the progress line
164
    log.info('Download complete!');
165
  }
166
}, 200);
167

168
// Processing with dynamic updates
169
const items = ['file1.txt', 'file2.txt', 'file3.txt'];
170
for (let i = 0; i < items.length; i++) {
171
  log.progress(`Processing ${items[i]} (${i + 1}/${items.length})`);
172
  await processFile(items[i]);
173
}
174
log.progress(''); // Clear when done
175
log.info('All files processed');
176
```
177

178
### Log Level Management
179

180
Control the minimum log level for individual logger instances.
181

182
```typescript { .api }
183
/**
184
 * Set log level for a specific logger instance
185
 * @param name - Logger name/identifier
186
 * @param level - Log level descriptor
187
 */
188
logger.setLevel(name: string, level: LogLevelDesc): void;
189
```
190

191
**Usage Examples:**
192

193
```typescript
194
import logger from '@wdio/logger';
195

196
// Set different levels for different components
197
logger.setLevel('database', 'debug');    // Show all database logs
198
logger.setLevel('api', 'warn');          // Only show API warnings and errors
199
logger.setLevel('verbose-module', 'silent'); // Suppress all logs
200

201
const dbLog = logger('database');
202
const apiLog = logger('api');
203

204
dbLog.debug('Database query executed'); // Will show (level is debug)
205
apiLog.debug('API request details');    // Won't show (level is warn)
206
apiLog.warn('API rate limit warning');  // Will show
207
```
208

209
## Types
210

211
```typescript { .api }
212
type LogLevelDesc = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
213
type LogLevelNumbers = 0 | 1 | 2 | 3 | 4 | 5;
214
```
215

216
## Environment Variables
217

218
- **WDIO_LOG_LEVEL**: Sets default log level for all loggers (default: 'info')
219
- **WDIO_DEBUG**: When set, changes default level to 'trace'
220
- **WDIO_LOG_PATH**: When set, creates a log file at the specified path
221
- **WDIO_LOG_MASKING_PATTERNS**: Global masking patterns (comma-separated regex strings)