# wdio session `wdio session` keeps one WebdriverIO session alive across many short shell commands. Use it to explore a UI, check a change, and turn the steps that worked into a test. It is part of `@wdio/cli` (WebdriverIO v10). ``` npx wdio session open chrome http://localhost:3000 npx wdio session snapshot --interactive npx wdio session click e3 npx wdio session export --out test/specs/cart.e2e.ts npx wdio session close ``` The session is named `default`. Pass `-s ` only when you need two sessions at once. The [targets](/docs/session/targets.md) page drives one Expo guinea pig in a headed Chrome window and in an Electron window, both at a desktop size. Android and iOS commands for the same app are on that page. ## Install[​](#install "Direct link to Install") `wdio session` is part of the WebdriverIO CLI. `npx wdio` installs the unscoped [`wdio`](https://www.npmjs.com/package/wdio) package and runs that CLI. You do not install `@wdio/session` yourself. ``` npx wdio session --help npx wdio session click --help ``` `--help` prints the workflow, the actions by group, global flags and exit codes. ` --help` prints that action's arguments, flags, platforms, examples and related actions. The same text is on the [commands](/docs/session-commands.md) page. The agent skill keeps only the core loop and sends agents to `--help` for the rest, so it does not go stale when the CLI changes. Scaffold a project with: ``` npm init wdio@latest ``` Accept "Set up coding agent support" to write `.agents/skills/wdio-session/SKILL.md`, an `AGENTS.md` section and a `.wdio/session/` gitignore entry. Install the skill later with: ``` npx wdio session skill --install . ``` `npx wdio session doctor` checks Node.js, the browser, Appium, SDKs and cloud credentials. `doctor ` checks only what that target needs. The process exits 1 when a check fails. ## Open a page and act on it[​](#open-a-page-and-act-on-it "Direct link to Open a page and act on it") Open headless Chrome (add `--headed` to show the window). `open` prints the page's interactive elements: ``` npx wdio session open chrome http://localhost:3000 ``` An element looks like `button "Add to cart" [ref=e3]`. Use that ref. Every action reports what it changed on the page, with refs for new elements, so you rarely need a separate `snapshot`: ``` npx wdio session click e3 npx wdio session exec -e "await expect($('aria/Cart (1)')).toBeDisplayed()" ``` `open firefox`, `open edge` and `open safari` take the same URL. Chrome, Firefox and Edge are downloaded on first use when they are not installed. Safari requires macOS. ### Android[​](#android "Direct link to Android") Android and iOS run through Appium 3. `doctor android` reports a missing server or driver with the install command. ``` npx wdio session doctor android npx wdio session open android --app ./shop.apk npx wdio session snapshot --interactive npx wdio session tap e3 ``` iOS: `open ios --bundle-id com.example.shop`. Native desktop: `open macos --bundle-id com.example.shop` and `open windows --app Root`. ### Electron[​](#electron "Direct link to Electron") ``` npx wdio session open electron ./main.js npx wdio session snapshot --interactive npx wdio session click e2 ``` `open tauri ./my-app` and `open dioxus ./my-app` need their driver on `PATH`. On Linux without `DISPLAY` or `WAYLAND_DISPLAY`, install Xvfb or weston. ## Observation and refs[​](#observation-and-refs "Direct link to Observation and refs") | Command | Use it for | | ------------------------ | ------------------------------------------------------------------------------------- | | `snapshot --interactive` | The elements you can act on, each with a ref | | `snapshot --compact` | The same tree with unnamed empty wrappers removed | | `snapshot --urls` | Link addresses on each link | | `find "Add to cart"` | A line from a fresh snapshot | | `diff` | What changed since the previous snapshot | | `screenshot` | Layout. Skip it when a snapshot answers the question | | `pdf` | A PDF of the current page (`pdf report.pdf`). BiDi sessions print headed and headless | | `source` | The page HTML or the native XML | Refs come from the latest snapshot. After navigation, snapshot again. An old ref fails with `REF_STALE`. An unknown ref fails with `REF_NOT_FOUND`. ## `exec`[​](#exec "Direct link to exec") `exec` runs WebdriverIO code. Always `await` commands. `$` returns one element and throws when it is missing. There is no sync mode and no `browser.element`. ``` npx wdio session exec -e "await browser.getTitle()" npx wdio session <<'JS' await $('aria/Cart (1)').waitForDisplayed() JS ``` Put assertions in `exec` with `expect-webdriverio`. Use `visual check ` (needs `@wdio/visual-service`) when the question is how the screen looks. ## Export[​](#export "Direct link to Export") `export` writes a spec from the recorded steps. Refs are replaced with stable selectors. ``` npx wdio session export --out test/specs/cart.e2e.ts npx wdio run wdio.conf.ts --spec test/specs/cart.e2e.ts npx wdio session close ``` `open firefox`, `open edge` and `open safari` take the same URL. Other targets, snapshots, `exec`, export and a paused test run are separate pages in this section. ## This section[​](#this-section "Direct link to This section") | Page | Use it for | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | [Targets](/docs/session/targets.md) | Browsers, Android, iOS, desktop, Electron, Tauri, Dioxus and cloud devices, including the demo app in Chrome, Android and Electron | | [Snapshots and refs](/docs/session/snapshots.md) | What is on screen, and the refs you click | | [Run code](/docs/session/exec.md) | `exec`, assertions and visual checks | | [Export a test](/docs/session/export.md) | Specs, page objects and `.wdio/helpers` | | [Debug a test](/docs/session/debug.md) | `wdio run --debug=agent` and `wdio repl --session` | | [Commands](/docs/session-commands.md) | Every action and flag | ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") | Message | What to do | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SESSION_EXISTS` | The name is already running. Use `-s` another name, or `open --replace`. | | `REF_STALE` / `REF_NOT_FOUND` | Run `snapshot` again and use a ref from that output. | | `NOT_EDITABLE` | The `fill` target is not an editable field and has no single editable field inside it (or behind `aria-controls`/`aria-owns`/label). Run `snapshot --scope ` and fill the field ref. | | `MISSING_DEPENDENCY` | Install the package named in the error, or run `wdio session doctor `. | | `MISSING_APPIUM_DRIVER` | Run the `npx appium driver install …` line from the error. | | `MISSING_CREDENTIALS` | Export the named variables. Doctor never prints their values. | | `Session closed from wdio session` | The debug session was closed. Resume instead of close when the test should continue. | Exit codes: 0 success, 1 the action failed, 2 usage, 3 a missing dependency or credentials, 4 no session with that name. ## Next steps[​](#next-steps "Direct link to Next steps") * [Targets](/docs/session/targets.md) — open a browser, an Android or iOS app, or an Electron window * [WebdriverIO for Coding Agents](/docs/ai-agents.md) — skill, docs and project rules * [wdio session commands](/docs/session-commands.md) — every action and flag