# Modules

WebdriverIO publishes various modules to NPM and other registries that you can use to build your own automation framework. See more documentation on WebdriverIO setup types [here](/docs/setuptypes.md).

## `webdriver` and `devtools`[​](#webdriver-and-devtools "Direct link to webdriver-and-devtools")

The protocol packages ([`webdriver`](https://www.npmjs.com/package/webdriver) and [`devtools`](https://www.npmjs.com/package/devtools)) expose a class with the following static functions attached that allow you to initiate sessions:

#### `newSession(options, modifier, userPrototype, customCommandWrapper)`[​](#newsessionoptions-modifier-userprototype-customcommandwrapper "Direct link to newsessionoptions-modifier-userprototype-customcommandwrapper")

Starts a new session with specific capabilities. Based on the session response commands from different protocols will be provided.

##### Paramaters[​](#paramaters "Direct link to Paramaters")

* `options`: [WebDriver Options](/docs/configuration.md#webdriver-options)
* `modifier`: function that allows to modify the client instance before it is being returned
* `userPrototype`: properties object that allows to extend the instance prototype
* `customCommandWrapper`: function that allows to wrap functionality around function calls

##### Returns[​](#returns "Direct link to Returns")

* [Browser](/docs/api/browser.md) object

##### Example[​](#example "Direct link to Example")

```
const client = await WebDriver.newSession({
    capabilities: { browserName: 'chrome' }
})
```

#### `attachToSession(attachInstance, modifier, userPrototype, customCommandWrapper)`[​](#attachtosessionattachinstance-modifier-userprototype-customcommandwrapper "Direct link to attachtosessionattachinstance-modifier-userprototype-customcommandwrapper")

Attaches to a running WebDriver or DevTools session.

##### Paramaters[​](#paramaters-1 "Direct link to Paramaters")

* `attachInstance`: instance to attach a session to or at least an object with a property `sessionId` (e.g. `{ sessionId: 'xxx' }`)
* `modifier`: function that allows to modify the client instance before it is being returned
* `userPrototype`: properties object that allows to extend the instance prototype
* `customCommandWrapper`: function that allows to wrap functionality around function calls

##### Returns[​](#returns-1 "Direct link to Returns")

* [Browser](/docs/api/browser.md) object

##### Example[​](#example-1 "Direct link to Example")

```
const client = await WebDriver.newSession({...})
const clonedClient = await WebDriver.attachToSession(client)
```

#### `reloadSession(instance)`[​](#reloadsessioninstance "Direct link to reloadsessioninstance")

Reloads a session given provided instance.

##### Paramaters[​](#paramaters-2 "Direct link to Paramaters")

* `instance`: package instance to reload

##### Example[​](#example-2 "Direct link to Example")

```
const client = await WebDriver.newSession({...})
await WebDriver.reloadSession(client)
```

## `webdriverio`[​](#webdriverio "Direct link to webdriverio")

Similar as to the protocol packages (`webdriver` and `devtools`) you can also use the WebdriverIO package APIs to manage sessions. The APIs can be imported using `import { remote, attach, multiremote } from 'webdriverio` and contain the following functionality:

#### `remote(options, modifier)`[​](#remoteoptions-modifier "Direct link to remoteoptions-modifier")

Starts a WebdriverIO session. The instance contains all commands as the protocol package but with additional higher order functions, see [API docs](/docs/api.md).

##### Paramaters[​](#paramaters-3 "Direct link to Paramaters")

* `options`: [WebdriverIO Options](/docs/configuration.md#webdriverio)
* `modifier`: function that allows to modify the client instance before it is being returned

##### Returns[​](#returns-2 "Direct link to Returns")

* [Browser](/docs/api/browser.md) object

##### Example[​](#example-3 "Direct link to Example")

```
import { remote } from 'webdriverio'

const browser = await remote({
    capabilities: { browserName: 'chrome' }
})
```

#### `attach(attachOptions)`[​](#attachattachoptions "Direct link to attachattachoptions")

Attaches to a running WebdriverIO session.

##### Paramaters[​](#paramaters-4 "Direct link to Paramaters")

* `attachOptions`: instance to attach a session to or at least an object with a property `sessionId` (e.g. `{ sessionId: 'xxx' }`)

##### Returns[​](#returns-3 "Direct link to Returns")

* [Browser](/docs/api/browser.md) object

##### Example[​](#example-4 "Direct link to Example")

```
import { remote, attach } from 'webdriverio'

const browser = await remote({...})
const newBrowser = await attach(browser)
```

#### `multiremote(multiremoteOptions)`[​](#multiremotemultiremoteoptions "Direct link to multiremotemultiremoteoptions")

Initiates a multiremote instance which allows you to control multiple session within a single instance. Checkout our [multiremote examples](https://github.com/webdriverio/webdriverio/tree/main/examples/multiremote) for concrete use cases.

##### Paramaters[​](#paramaters-5 "Direct link to Paramaters")

* `multiremoteOptions`: an object with keys representing the browser name and their [WebdriverIO Options](/docs/configuration.md#webdriverio).

##### Returns[​](#returns-4 "Direct link to Returns")

* [Browser](/docs/api/browser.md) object

##### Example[​](#example-5 "Direct link to Example")

```
import { multiremote } from 'webdriverio'

const matrix = await multiremote({
    myChromeBrowser: {
        capabilities: { browserName: 'chrome' }
    },
    myFirefoxBrowser: {
        capabilities: { browserName: 'firefox' }
    }
})
await matrix.url('http://json.org')
await matrix.getInstance('browserA').url('https://google.com')

console.log(await matrix.getTitle())
// returns ['Google', 'JSON']
```

#### `Key`[​](#key "Direct link to key")

An object containing special character constants for use with the [`browser.keys`](/docs/api/browser/keys.md) command. These constants represent special keys that can be sent to the browser, such as `Enter`, `Tab`, `Escape`, arrow keys, function keys, and more.

##### Example[​](#example-6 "Direct link to Example")

```
import { Key } from 'webdriverio'

// Press Enter key
await browser.keys(Key.Enter)

// Use Ctrl+A to select all (works cross-platform)
await browser.keys([Key.Ctrl, 'a'])

// Navigate with arrow keys
await browser.keys([Key.ArrowDown, Key.ArrowDown, Key.Enter])
```

##### Available Keys[​](#available-keys "Direct link to Available Keys")

The following special keys are available via the `Key` object:

**Modifier Keys:**

| Constant      | Description                                                           |
| ------------- | --------------------------------------------------------------------- |
| `Key.Ctrl`    | Cross-platform control key (Command on Mac, Control on Windows/Linux) |
| `Key.Control` | Control key                                                           |
| `Key.Shift`   | Shift key                                                             |
| `Key.Alt`     | Alt key                                                               |
| `Key.Command` | Command key (Mac)                                                     |
| `Key.NULL`    | Null/release key — releases all currently held modifier keys          |

**Navigation Keys:**

| Constant         | Description     |
| ---------------- | --------------- |
| `Key.Cancel`     | Cancel key      |
| `Key.Help`       | Help key        |
| `Key.Backspace`  | Backspace key   |
| `Key.Tab`        | Tab key         |
| `Key.Clear`      | Clear key       |
| `Key.Return`     | Return key      |
| `Key.Enter`      | Enter key       |
| `Key.Pause`      | Pause key       |
| `Key.Escape`     | Escape key      |
| `Key.Space`      | Space key       |
| `Key.PageUp`     | Page Up key     |
| `Key.PageDown`   | Page Down key   |
| `Key.End`        | End key         |
| `Key.Home`       | Home key        |
| `Key.ArrowLeft`  | Left Arrow key  |
| `Key.ArrowUp`    | Up Arrow key    |
| `Key.ArrowRight` | Right Arrow key |
| `Key.ArrowDown`  | Down Arrow key  |
| `Key.Insert`     | Insert key      |
| `Key.Delete`     | Delete key      |

**Character Keys:**

| Constant        | Description   |
| --------------- | ------------- |
| `Key.Semicolon` | Semicolon key |
| `Key.Equals`    | Equals key    |

**Numpad Keys:**

| Constant                      | Description      |
| ----------------------------- | ---------------- |
| `Key.Numpad0` - `Key.Numpad9` | Numpad 0-9       |
| `Key.Multiply`                | Numpad Multiply  |
| `Key.Add`                     | Numpad Add       |
| `Key.Separator`               | Numpad Separator |
| `Key.Subtract`                | Numpad Subtract  |
| `Key.Decimal`                 | Numpad Decimal   |
| `Key.Divide`                  | Numpad Divide    |

**Function Keys:**

| Constant             | Description                  |
| -------------------- | ---------------------------- |
| `Key.F1` - `Key.F12` | Function keys F1 through F12 |

**Other Keys:**

| Constant             | Description                    |
| -------------------- | ------------------------------ |
| `Key.ZenkakuHankaku` | Zenkaku/Hankaku key (Japanese) |

Cross-Platform Modifier Keys

The `Key.Ctrl` constant provides a convenient way to use the "control" modifier across different operating systems. On macOS, it maps to the `Command` key, while on Windows and Linux it maps to the `Control` key. This is useful when writing tests that need to work across multiple platforms, e.g., for select-all (`Ctrl+A`), copy (`Ctrl+C`), or paste (`Ctrl+V`) operations.

## `@wdio/cli`[​](#wdiocli "Direct link to wdiocli")

Instead of calling the `wdio` command, you can also include the test runner as module and run it in an arbitrary environment. For that, you'll need to require the `@wdio/cli` package as module, like this:

* EcmaScript Modules
* CommonJS

```
import Launcher from '@wdio/cli'
```

```
const Launcher = require('@wdio/cli').default
```

After that, create an instance of the launcher, and run the test.

#### `Launcher(configPath, opts)`[​](#launcherconfigpath-opts "Direct link to launcherconfigpath-opts")

The `Launcher` class constructor expects the URL to the config file, and an `opts` object with settings that will overwrite those in the config.

##### Paramaters[​](#paramaters-6 "Direct link to Paramaters")

* `configPath`: path to the `wdio.conf.js` to run
* `opts`: arguments ([`<RunCommandArguments>`](https://github.com/webdriverio/webdriverio/blob/main/packages/wdio-cli/src/types.ts#L51-L77)) to overwrite values from the config file

##### Example[​](#example-7 "Direct link to Example")

```
const wdio = new Launcher(
    '/path/to/my/wdio.conf.js',
    { spec: '/path/to/a/single/spec.e2e.js' }
)

wdio.run().then((exitCode) => {
    process.exit(exitCode)
}, (error) => {
    console.error('Launcher failed to start the test', error.stacktrace)
    process.exit(1)
})
```

The `run` command returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). It is resolved if tests ran successfully or failed, and it is rejected if the launcher was unable to start run the tests.

## `@wdio/browser-runner`[​](#wdiobrowser-runner "Direct link to wdiobrowser-runner")

When running unit or component tests using WebdriverIO's [browser runner](/docs/runner.md#browser-runner) you can import mocking utilities for your tests, e.g.:

```
import { fn, spyOn, mock, unmock } from '@wdio/browser-runner'
```

The following named exports are available:

#### `fn`[​](#fn "Direct link to fn")

Mock function, see more in the official [Vitest docs](https://vitest.dev/api/mock.html#mock-functions).

#### `spyOn`[​](#spyon "Direct link to spyon")

Spy function, see more in the official [Vitest docs](https://vitest.dev/api/mock.html#mock-functions).

#### `mock`[​](#mock "Direct link to mock")

Method to mock file or dependency module.

##### Paramaters[​](#paramaters-7 "Direct link to Paramaters")

* `moduleName`: either a relative path to the file to be mocked or a module name.
* `factory`: function to return the mocked value (optional)

##### Example[​](#example-8 "Direct link to Example")

```
mock('../src/constants.ts', () => ({
    SOME_DEFAULT: 'mocked out'
}))

mock('lodash', (origModuleFactory) => {
    const origModule = await origModuleFactory()
    return {
        ...origModule,
        pick: fn()
    }
})
```

#### `unmock`[​](#unmock "Direct link to unmock")

Unmock dependency that is defined within the manual mock (`__mocks__`) directory.

##### Paramaters[​](#paramaters-8 "Direct link to Paramaters")

* `moduleName`: name of the module to be unmocked.

##### Example[​](#example-9 "Direct link to Example")

```
unmock('lodash')
```