@wdio/logger/README.md

A helper utility for logging of WebdriverIO packages

WDIO Logger Utility
===================

> A helper utility for logging of WebdriverIO packages

This package is used across all WebdriverIO packages to log information using the [`loglevel`](https://www.npmjs.com/package/loglevel) package. It can also be used for any other arbitrary Node.js project.

## Install

To install the package just call

```sh
npm install @wdio/logger
```

or when adding it to a WebdriverIO subpackage:

```sh
lerna add @wdio/logger --scope <subpackage>
```

## Usage

The package exposes a logger function that you can use to register an instance for your scoped package:

```js
import logger from '@wdio/logger'

const log = logger('myPackage')
log.info('some logs')
```

For more info see [`loglevel`](https://www.npmjs.com/package/loglevel) package on NPM.

## Custom Log Levels

This package extends the log levels available in [`loglevel`](https://www.npmjs.com/package/loglevel) by introducing a new level called `progress`.

The `progress` level is particularly useful when you need to dynamically update a specific line in the terminal. For example, it can be utilized to display the download progress of browsers or drivers.

Notably, the `progress` level is equivalent to the `info` level. Therefore, if you set the log level to `error` or `silent`, any `progress` logs will be suppressed.

It's important to mention that `progress` writes directly to `process.stdout`, and these logs won't be captured in any log files.

To ensure consistent formatting with subsequent logs while using `progress`, it's essential to clear it at the end. To do so, simply call `progress` with an empty string, which will clear the last line:

```
log.progress('')
```

### Illustrative Usage of Progress

```javascript
import logger from '@wdio/logger';

const log = logger('internal');

const totalSize = 100;
let uploadedSize = 0;

const uploadInterval = setInterval(() => {
	const chunkSize = 10;
	uploadedSize += chunkSize;
	const data = `Progress: ${(uploadedSize * 100) / totalSize}%`;
	log.progress(data);
	if (uploadedSize >= totalSize) {
		clearInterval(uploadInterval);
		log.progress(''); // Called at the end to maintain the alignment of subsequent logs.
		console.log('Upload complete.');
	}
}, 100);
```

## Masking Patterns

For more secure logging, `setMaskingPatterns`, `WDIO_LOG_MASKING_PATTERNS` or `maskingPatterns` can obfuscate sensitive information from the log.
For example, we can replace `--key=MySecretKey` with `--key=**MASKED**` to hide your cloud service access key or secret key
 - The regular expression pattern must be provided as a string similar as a RegEx but as string type, for example, `--key=[^ ]*`
 - It support flags and capturing groups like `/--key=([^ ]*)/i`
 - Multiple patterns are separated by a comma, like `--key=([^ ]*),secrets=([^ ]*)`
 - If no capturing group is provided, the entire matching string of the pattern is masked
 - If one or more capturing groups are provided, we replace all the matching groups with `**MASKED**`
 - If there are multiple matches for a single group, we replace them all, too
 - Support both masking in a file and the console
    - Note: In the console, when masking, some colors get stripped, which is a known limitation

`setMaskingPatterns` example
 ```javascript
import logger from '@wdio/logger';

// Default for all loggers
logger.setMaskingPatterns('/--key=([^ ]*)/i,/--secrets=([^ ]*)/i')

// For a specific logger
logger.setMaskingPatterns({'internal' : '/--key=([^ ]*)/i,/--secrets=([^ ]*)/i'})
const log = logger('internal');
```

Using wdio config from a `conf.ts` file, we can also configure masking patterns
```javascript
export const config: WebdriverIO.Config = {
    /**
     * test configurations
     */
    logLevel: 'debug',
    maskingPatterns: '/--key=([^ ]*)/i,/--secrets=([^ ]*)/i',
}
```

For secrets passed via the command line, masking may fail because the wdio.conf.ts file is parsed later in the execution cycle. Using environment variables for these cases is highly recommended and much safer.

Below are examples with the environment variable `WDIO_LOG_MASKING_PATTERNS` in the code directly:

```javascript
// Using environment variable in code
process.env.WDIO_LOG_MASKING_PATTERNS = '/--key=([^ ]*)/i,/--secrets=([^ ]*)/i'
```

Or before your command line
```shell
WDIO_LOG_MASKING_PATTERNS='RESULT ([^ ]*)' npx wdio run ./wdio/wdio.conf.ts
```