@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);
```