# @wdio/session

> Drive browsers, mobile apps and desktop apps with WebdriverIO from the shell

Latest version **10.2.0** (published 2026-11-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install @wdio/session
pnpm add @wdio/session
yarn add @wdio/session
bun add @wdio/session
```

Provides the command `wdio-session`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 10.2.0 |
| Published | 2026-11-06 |
| First published | 2026-10-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=22.23.4 <23 \|\| >=24.22.1 <25 \|\| >=26.12.1 |
| Dependencies | 13 |
| Unpacked size | 1.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 9869 |
| Author | Christian Bromann |
| Maintainers | christian-bromann, wdio-user, wswebcreation-nl |
| Keywords | webdriverio, wdio, session, cli, agent, automation |

## Links

- npm: https://www.npmjs.com/package/@wdio/session
- Repository: https://github.com/webdriverio/webdriverio
- Homepage: https://github.com/webdriverio/webdriverio/tree/main/packages/wdio-session
- Issues: https://github.com/webdriverio/webdriverio/issues
- npm.io page: https://npm.io/package/@wdio/session

## Dependencies (13)

- [acorn](https://npm.io/package/acorn.md) ^8.15.0
- [yargs](https://npm.io/package/yargs.md) ^18.2.0
- [semver](https://npm.io/package/semver.md) ^7.7.4
- [get-port](https://npm.io/package/get-port.md) ^7.1.0
- [picomatch](https://npm.io/package/picomatch.md) ^4.0.7
- [image-size](https://npm.io/package/image-size.md) ^2.0.4
- [@types/node](https://npm.io/package/@types/node.md) ^22.20.4
- [@wdio/types](https://npm.io/package/@wdio/types.md) 10.2.0
- [@wdio/utils](https://npm.io/package/@wdio/utils.md) 10.2.0
- [@wdio/config](https://npm.io/package/@wdio/config.md) 10.2.0
- [@wdio/logger](https://npm.io/package/@wdio/logger.md) 10.2.0
- [@wdio/snapshot](https://npm.io/package/@wdio/snapshot.md) 10.2.0
- [@wdio/display-server](https://npm.io/package/@wdio/display-server.md) 10.2.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 10.2.0 (latest) — 2026-11-06
- 10.2.0-alpha.100.sha-b38abd894 (next) — 2026-10-31
- 10.1.0 — 2026-10-18
- 10.0.2 — 2026-10-08
- 10.1.0-alpha.30 — 2026-10-07
- 10.1.0-alpha.29 — 2026-10-07
- 10.0.1 — 2026-10-07
- 10.1.0-alpha.26 — 2026-10-06
- 10.0.0 — 2026-10-05
- 10.0.0-alpha.175 — 2026-10-04
- 10.0.0-alpha.165 — 2026-10-04
- 10.0.0-alpha.163 — 2026-10-04
- 10.0.0-alpha.172 — 2026-10-04
- 10.0.0-alpha.171 — 2026-10-04
- 10.0.0-alpha.166 — 2026-10-04
- … 5 more at https://npm.io/package/@wdio/session/versions

## README

WebdriverIO Session
===================

> Drive browsers, mobile apps and desktop apps with WebdriverIO from the shell.

`wdio session` starts a WebdriverIO session that outlives the command that
created it, so a coding agent (or a human) can automate an app with many short
shell commands and turn what worked into a test.

```sh
npx wdio session open chrome http://localhost:3000
npx wdio session snapshot
npx wdio session click e3
npx wdio session <<'JS'
await expect($('aria/Cart (1)')).toBeDisplayed()
JS
npx wdio session export --out test/specs/cart.e2e.ts
npx wdio session close
```

The command is part of `@wdio/cli`. `npx wdio` installs the unscoped
[`wdio`](https://www.npmjs.com/package/wdio) package, which runs that CLI, so
you do not install `@wdio/session` or `@wdio/cli` first. For the full guide, see
[webdriver.io/docs/session](https://webdriver.io/docs/session).
Check a machine with `npx wdio session doctor`. Agents install the skill with
`npx wdio session skill --install .`.

## Use the actions from code

Install `webdriverio` next to this package: it is a required peer dependency.

`@wdio/session/agent` runs the same actions, snapshots and refs on a browser
your code already owns, for example in a test or a `remote()` script. There is
no daemon. `dispose()` leaves the browser session open.

> **Experimental:** the `@wdio/session/agent` API, the snapshot text and the
> `RefEntry` fields `ref()` returns may change in a minor release. The ref
> syntax (`e3`) and the code an action records stay stable.

```ts
import { remote } from 'webdriverio'
import { createAgentSession } from '@wdio/session/agent'

const browser = await remote({ capabilities: { browserName: 'chrome' } })
const agent = await createAgentSession(browser, { captureEvents: true })

await browser.url('http://localhost:3000')
const { text } = await agent.snapshot({ interactive: true })
const { code } = await agent.run('click', { target: 'e3' })
console.log(code) // await $('role/button[name="Add to cart"]').click()

await agent.dispose()
await browser.deleteSession()
```

`run(action, args)` type-checks the action name and its arguments against the
action specs: positionals and options are camelCased (`--max-chars` becomes
`maxChars`) and a variadic positional is one string. A typo is a compile error.
Use `runAction(name, args)` when the name is only known at runtime, for example
from a recorded step. It takes untyped arguments.

`snapshot(opts)` returns an `AgentSnapshot`: `text`, the `tree`, and the
`lines`, `refs` and `chars` counts, plus `page` and `notes` when there are any.
`maxChars` caps the size. Above it `tooBig` is `true` and `text` is a summary.
It writes no file and works for app (Appium) sessions too.

Action results carry structured fields next to `text` and `code`:

- `changes`: what the page shows after the action, a `PageChange` of kind
  `page` (a navigation or new frame), `changed` (added elements) or `removed`.
- `noVisibleChange`: `true` after a click or tap that changed nothing.
- `page` and `notes`: the URL and title, and load-error or bot-check notes.
- `data`: typed per action, for example `get` gives `{ text, value, ... }`.

Hints in the output name `wdio session` commands. The `hint` option rewrites
them for your own tools. Return `undefined` to keep the CLI text:

```ts
const tools: Record<string, string> = { snapshot: 'page_snapshot', click: 'page_click' }
const agent = await createAgentSession(browser, {
    hint: (command) => (tools[command] ? `${tools[command]}()` : undefined)
})
```

Failures throw `SessionError`, with a `code` of type `ErrorCode`. Both are
exported from `@wdio/session/agent`.

`tsx` and `expect-webdriverio` are optional peer dependencies. `expect` inside
`exec` needs `expect-webdriverio` installed in your project. TypeScript configs
load without `tsx` through Node type stripping or jiti.

---
_Source: https://npm.io/package/@wdio/session · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._