wdio-session

wdio session

wdio session keeps one WebdriverIO session alive between short shell commands. Use it to see or drive a real browser, mobile app, or desktop app, check a change, and turn the steps that worked into a test. Use curl or fetch instead when the question is only about an HTTP API.

The loop

npx wdio session open chrome https://example.com
npx wdio session click e3
npx wdio session fill e5 Ada Lovelace && npx wdio session select e6 Pro && npx wdio session check e7 && npx wdio session click e8
npx wdio session get text e9

Open once. Browsers run headless. open prints the page's interactive elements, so you can act right away. It also takes firefox, edge, safari, android, ios, electron <app> and more.
Act on refs. Elements show up as button "Add to cart" [ref=e3]. Refs stay valid while the element exists.
Every action reports what changed: new or changed lines with their refs (+ status "Saved"), or the new page's elements after a navigation. You rarely need a separate snapshot.
Chain steps with &&. One shell call for several steps is faster, and a failing step stops the chain. Keep the steps that show the result (the filter that got applied, the item you picked) in calls of their own.
Big page? find <text> prints only the matching part of the page, with refs, and scrolls it into view. A long snapshot prints in parts: --offset <line> gives the next one. read gives an article's text.
snapshot --viewport shows only what is on screen. On the web it does not update the baseline diff compares with; run a plain snapshot (or snapshot -i) first to refresh it.
Output is ready to read. No need for head, grep, sed, redirects or sleep: use find, snapshot --offset and wait 2000.
Show your answer. Before you answer, leave the page on what proves it (find/scroll to it): what's on screen is the evidence.
No need to close. The session shuts itself down when idle. Run close only to start over.

Actions

Action	Example
Look	`snapshot -i` (interactive only) · `snapshot` (with text) · `find "Add to cart"` · `read` (page text) · `screenshot`
Click	`click e3` · `click e3 --double` · `hover e3` · `scroll down` · `scroll e3`
Text	`fill e2 Ada Lovelace` (replaces) · `type e2 more` (appends) · `press Enter` · `press ArrowRight --times 5`
Values	`fill e4 65` sets sliders, dates and colors too
Forms	`select e4 Pro` · `check e5` · `uncheck e5` · `upload e6 ./file.pdf`
Read	`get text e9` · `get value e2` · `get url` · `get title` · `is visible e3`
Wait	`wait e3` · `wait --text "Saved"` · `wait --url /done` · `wait 2000`
Navigate	`navigate https://…` · `back` · `reload` · `tabs` · `tabs switch 1`
Frames	refs inside iframes work as they are · `frame e1` scopes snapshots to the iframe e1 · `frame top`
Code	`exec -e 'console.log(await $("h1").getText())'`

Run npx wdio session <action> --help only when an action fails or you need a flag that isn't shown here.

Code

Use exec for loops, conditions and assertions. It runs in Node with browser and $ in scope; page code goes in await browser.execute(() => …). Pipe longer code on stdin:

npx wdio session exec -e 'await expect($("h1")).toHaveText("Cart")'
npx wdio session exec <<'JS'
await $('aria/Sign in').click()
await expect(browser).toHaveUrl(expect.stringContaining('/dashboard'))
JS

WebdriverIO v10 rules: always await commands; $ returns exactly one element and throws StrictSelectorError on more than one match; wrap code in single quotes so the shell does not run $(…).

Turn it into a test

Every action prints the WebdriverIO code it ran (→ …). export writes those steps as a spec:

npx wdio session export --out test/specs/cart.e2e.ts
npx wdio run wdio.conf.ts --spec test/specs/cart.e2e.ts

No wdio.conf.ts yet? npm init wdio@latest . -- --yes --typescript --framework mocha --browsers chrome --reporters spec

Debug a failing test

npx wdio run wdio.conf.ts --debug=agent
npx wdio session -s debug-0-0 snapshot -i
npx wdio session -s debug-0-0 resume

Errors

Exit codes: 1 the action or your code failed, 2 usage error, 3 missing dependency or credentials, 4 no session with that name. Errors print a hint on the next line. npx wdio session doctor checks the machine.