Skip to main content

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 <name> only when you need two sessions at once. The targets 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​

wdio session is part of the WebdriverIO CLI. npx wdio installs the unscoped 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. <action> --help prints that action's arguments, flags, platforms, examples and related actions. The same text is on the commands 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 <target> checks only what that target needs. The process exits 1 when a check fails.

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 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​

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​

CommandUse it for
snapshot --interactiveThe elements you can act on, each with a ref
snapshot --compactThe same tree with unnamed empty wrappers removed
snapshot --urlsLink addresses on each link
find "Add to cart"A line from a fresh snapshot
diffWhat changed since the previous snapshot
screenshotLayout. Skip it when a snapshot answers the question
pdfA PDF of the current page (pdf report.pdf). BiDi sessions print headed and headless
sourceThe 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 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 <tag> (needs @wdio/visual-service) when the question is how the screen looks.

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​

PageUse it for
TargetsBrowsers, Android, iOS, desktop, Electron, Tauri, Dioxus and cloud devices, including the demo app in Chrome, Android and Electron
Snapshots and refsWhat is on screen, and the refs you click
Run codeexec, assertions and visual checks
Export a testSpecs, page objects and .wdio/helpers
Debug a testwdio run --debug=agent and wdio repl --session
CommandsEvery action and flag

Troubleshooting​

MessageWhat to do
SESSION_EXISTSThe name is already running. Use -s another name, or open --replace.
REF_STALE / REF_NOT_FOUNDRun snapshot again and use a ref from that output.
NOT_EDITABLEThe 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 <target> and fill the field ref.
MISSING_DEPENDENCYInstall the package named in the error, or run wdio session doctor <target>.
MISSING_APPIUM_DRIVERRun the npx appium driver install … line from the error.
MISSING_CREDENTIALSExport the named variables. Doctor never prints their values.
Session closed from wdio sessionThe 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​

Welcome! How can I help?

WebdriverIO AI Copilot