webdriverio/webdriverio
github.com/webdriverio/webdriverio ↗ · 797 files · 2.9 MB
Next-gen browser and mobile automation test framework for Node.js.
Overview
WebdriverIO is a Node.js automation framework for developers testing websites, browser components, and mobile applications through WebDriver, WebDriver BiDi, and Appium. This monorepo combines standalone browser clients, a CLI that schedules isolated test workers, framework adapters, services, reporters, and a Vite-based browser runner. Its distinctive architecture layers resilient element commands and session managers over protocol bindings while allowing runners, commands, locators, and integrations to be extended.
System map
The product is a collection of cooperating packages rather than one deployed application. Standalone clients and CLI test execution share protocol bindings but have different lifecycle owners. Node workers, real browsers, driver processes, and optional cloud backends form the principal runtime boundaries. Build artifacts are published as packages, while the documentation website has a separate deployment workflow.
- The private ESM root workspace selects pnpm 10.34.5; workspace membership includes packages, compiler infrastructure, website, e2e, typing fixtures, and selected examples.
- webdriverio exposes browser, Node ESM, and CommonJS entrypoints; its Node source installs filesystem-backed helpers and process environment access into the shared environment object.
- The webdriver package owns session creation and protocol composition: WebDriver.newSession starts a driver, negotiates capabilities, constructs a client monad, and optionally connects BiDi.
- The wdio executable imports the compiled CLI; run() dispatches registered commands or treats a configuration path as the default run command.
- Launcher owns capability scheduling and worker capacity; local workers execute @wdio/runner and exchange commands and results through Node IPC.
- BrowserRunner extends LocalRunner, requires Mocha, starts Vite servers for worker runs, registers a server-worker communicator, and aggregates coverage during shutdown.
- The inspected storage boundaries are caller-selected artifact files and an optional process-memory shared store served over loopback HTTP.
- Root scripts define build, unit, typing, smoke, component, and e2e checks; CI uploads compiled package artifacts, manual publishing invokes Lerna, and documentation deployment invokes the separate docs pipeline.
Feature catalog
The inspected public surface spans direct automation APIs and configuration-driven test execution. Browser and element command barrels expose navigation, inspection, interaction, waiting, emulation, and artifact operations. Mobile commands and cloud endpoint selection extend the same client model beyond desktop browsers. Browser component testing, network mocking, snapshots, and shared resource pools have explicit runtime conditions.
- remote creates a session, attach wraps an existing session, and multiremote coordinates named browser sessions; multiremote initialization opens constituent sessions concurrently.
- The CLI registers config, install, repl, and run; run accepts suite/spec selection, exclusions, repetition, sharding, headless mode, watch mode, snapshot updates, and CPU/heap profiling options.
- Browser exports include URL/window/frame navigation, cookies, synchronous/asynchronous script execution, keyboard and pointer actions, viewport sizing, emulation, throttling, and Puppeteer access.
- Element exports include value entry, clicking, dragging, selection, text/attribute/CSS inspection, accessibility role/label retrieval, state checks, shadow/React selectors, and explicit wait commands.
- Mobile exports cover native/webview contexts, app lifecycle, deep links, gestures, clipboard, device locking, connectivity controls, biometrics, and emulator telephony/power operations.
- detectBackend selects BrowserStack, TestingBot, Sauce Labs, or LambdaTest defaults using credential shape and provider options; explicit connection values can override those defaults.
- Browser component testing uses Vite and documented React, Preact, Vue, Svelte, Solid, and Stencil presets; the implementation rejects frameworks other than Mocha.
- BiDi-only browser.mock replaces identical mock definitions; screenshot capture supports Classic PNG or BiDi PNG/JPEG options, while runner services supply snapshots, soft assertions, and shared-store get/set/resource-pool APIs.
Data flow
Configuration is executable input that becomes launcher scheduling state and is reconstructed in each worker. Session requests transform requested capabilities into negotiated capabilities and protocol-specific client state. Element lookup preserves references and selectors so middleware can recover from missing or stale elements. Outputs cross distinct boundaries: IPC reporting, driver HTTP/WebSocket traffic, local artifact files, and optional loopback shared-store requests.
- ConfigParser.initialize loads the configuration module once, merges overrides, and applies CLI headless settings; addConfigFile extracts capabilities and hooks before deep-merging remaining configuration.
- getSpecs resolves configured files, applies capability specs unless CLI --spec is present, combines requested suites, deduplicates, conditionally repeats, filters exclusions, and then shards.
- Launcher structured-clones capabilities for each worker, runs onWorkerStart hooks, and passes configuration path, selected specs, credentials, execArgv, and retries to runner.run.
- startWebDriverSession converts flat capabilities to alwaysMatch/firstMatch, requests BiDi except for enforced Classic or Safari, normalizes overlaps, sends POST /session, and writes negotiated capabilities back to params.
- Protocol command wrappers validate arguments, encode endpoint variables, construct an unmasked request body, produce masked event/log payloads, and delegate execution to environment.value.Request.
- getElement converts protocol references into client objects containing elementId, selector, parent, and optional BiDi locator; the element command wrapper uses these fields for waiting and stale-reference recovery.
- Worker browser command/result events become reporter events; BaseReporter fans out events, sends output through IPC when available, and shutdown waits for reporter synchronization before emitting exit.
- Shared-store launcher startup injects the server port into capabilities; worker service setup installs browser.sharedStore, whose client serializes JSON over loopback HTTP into an object store or resource-pool Map.
Behavior traces
Three concrete flows were followed through implementation: CLI test execution, element lookup and click, and screenshot persistence. Startup includes configuration import, worker scheduling, framework discovery, session creation, and teardown. Element interaction changes behavior according to runner environment, protocol support, and error conditions. Screenshot persistence separates capture selection from filesystem output.
- Startup 1: wdio.js imports the compiled CLI → run() parses commands → the run handler checks the configuration path and resolves TypeScript settings → launch() constructs Launcher and calls run(); --watch instead enters Watcher.watch().
- Startup 2: Launcher.run → initialize/ConfigParser.initialize → runner plugin construction → launcher services → runner.initialize → user and service onPrepare hooks → driver/browser setup → _runMode/_runSpecs → _startInstance and runner.run.
- Startup 3: worker IPC dispatch invokes Runner.run → worker config import → stub session → worker services and beforeSession → reporters/framework discovery → real _initSession when tests exist → before hook → framework.run → endSession outside watch mode → snapshot IPC → _shutdown.
- Action 1: browser.$ delegates string selectors through globalThis.wdio in browser-runner mode; otherwise it calls findElement and getElement. Eligible BiDi string lookups use findDeepElement, while regular lookups dispatch findElement or findElementFromElement.
- Action 2: getElement installs elementErrorHandler(wrapCommand) → implicitWait waits and requeries missing elements except explicit waits/state checks and selected native scroll operations → middleware updates elementId → command executes; non-interactable and stale failures enter separate recovery branches.
- Action 3: click without options calls elementClick → POST /session/:sessionId/element/:elementId/click → request.makeRequest; intercepted clicks scroll to center and retry. Options instead build pointer move/down/pause/up actions and honor skipRelease.
- Persistence 1: browser.saveScreenshot → environment.value.saveScreenshot installed by node.ts → Node saveScreenshot checks filepath type → path.resolve → assertDirectoryExists → chooses takeScreenshotClassic or takeScreenshotBidi.
- Persistence 2: Classic validates PNG/no options and calls takeScreenshot; BiDi obtains context/tree, validates format/quality/clip, and uses an html element screenshot inside an iframe or browsingContextCaptureScreenshot otherwise. The returned base64 becomes a Buffer, fs.writeFile persists it, and the Buffer is returned.
Testing signals
Tests and CI were inspected, not executed; their existence does not establish passing results. The bounded inspection found Vitest unit tests, type compilation fixtures, a custom smoke harness, real-browser e2e suites, and component tests. Mock-heavy unit coverage is complemented by selected integration tests, but configuration deliberately suppresses some error and coverage signals. CI execution depends on changed paths, branch, operating system, and selected matrix mode.
- The inspected unit suite uses Vitest and packages/**/*.test.ts, globally installs a fetch mock, and sets WDIO_SKIP_DRIVER_SETUP=1; this investigation produced no unit-test execution result.
- Unit configuration sets dangerouslyIgnoreUnhandledErrors and typecheck.ignoreSourceErrors, disables coverage by default, and excludes the BiDi handler from coverage; watermark values are configured but are not evidence of achieved coverage.
- Screenshot unit tests mock filesystem access/writes and browser capture calls; inspected cases cover Classic options rejection, BiDi iframe/full-page/clip behavior, and invalid format, extension, quality, or clip inputs.
- Request tests mock Undici and fetch, then assert fresh timeout signals across retries, preservation of transformRequest signals, per-session dispatcher reuse, and cleanup specifically on session deletion.
- Launcher tests mock config, logging, and driver setup; inspected test declarations cover retry requeue ordering, worker limits, grouped specs, hooks, and shutdown. Shared-store tests instead explicitly start a server and issue fetch requests.
- The smoke harness runs selected tests sequentially in CI and all tests concurrently locally without a filter; contributor documentation explains that its mock WebDriver service supplies predefined driver responses.
- Real-browser examples include DOM snapshots and masked input, while React component tests render and click a component. However, the Preact and miscellaneous component scripts use successful echo commands before ||, bypassing their wdio commands.
- Inspected CI selects suites by changed paths, uses full or reduced Node/OS unit matrices, gates cloud tests to main, and builds English plus Arabic documentation. Typing checks compile webdriver, webdriverio, Mocha, Jasmine, and Cucumber fixtures; none of these checks was executed here.
Risk map
These are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. The most consequential boundaries accept executable configuration, launch processes, communicate with drivers, and write caller-selected artifacts. Credential transport and logging depend on protocol and masking choices. Testing configuration and browser compatibility branches also create limits on what source inspection alone can establish.
- Configuration and plugins are executable inputs: ConfigParser imports the selected config module, initializePlugin imports scoped/absolute or convention-derived modules, and automationProtocol can select a dynamically imported driver.
- Process-launch boundaries inherit environment settings and accept runtime arguments; Chromium startup can download/select a driver binary, defaults allowedOrigins to '*' and allowedIps to '0.0.0.0', and accepts spawnOpts overrides.
- BiDi connection options follow up to ten redirects and forward custom headers; strictSSL=false disables certificate verification. The source explicitly identifies cross-host credential forwarding as a consequence of misconfigured redirects.
- HTTP session authentication uses a Basic header on /session. LambdaTest auto-detection defaults to HTTP port 80 unless overridden, and enabled Appium direct connection replaces host/protocol/path/port from returned capabilities.
- Input masking covers selected request/log payloads, but command result values are logged; the e2e masked-input example explicitly warns that a later getValue exposes the password in logs.
- Screenshot writes resolve caller paths without a repository-root constraint. BrowserRunner.initialize recursively removes an existing configured reports directory when clean is absent or true, so artifact configuration controls filesystem effects.
- Shared-store routes bind to loopback and expose get/set/pool operations without authentication middleware in the inspected chain. validateBody checks only paths ending /get or /set, while the primary setter is POST /; this mismatch warrants investigation, not a confirmed exploit claim.
- Hypothesis: compatibility regressions may escape narrow mocked checks because locator behavior combines protocol fallbacks, browser-version workarounds, shadow-root state, and stale-element recovery, while unit configuration suppresses unhandled-error and default coverage signals. (inferred)
Extension points
Extension is built into both user configuration and package internals. Name-based plugin loading supports official and community packages, while service activation distinguishes launcher and worker responsibilities. Command barrels and protocol descriptor tables construct client APIs. Custom locators, framework adapters, reporters, automation drivers, and compiler plugins provide additional integration seams.
- initializePlugin resolves scoped or absolute imports first, then @wdio/<name>-<type>, then wdio-<name>-<type>, and throws an actionable error when no candidate loads.
- Services accept existing hook objects, classes, or package names; package launcher exports run in the parent, and shouldLoad(config, caps) can prevent a package from being imported into workers.
- Browser and element commands enter their scopes through export barrels; applyScopePrototype enumerates those exports and excludes names listed in IGNORED_COMMAND_FILE_EXPORTS.
- addCommand and overwriteCommand are propagated across multiremote instances; runner session replacement also preserves custom and overwritten commands registered against the preliminary stub.
- addLocatorStrategyHandler stores named functions in a strategies Map, rejects duplicate names, and propagates registrations to multiremote constituent instances.
- automationProtocol selects the Driver factory or protocol stub; protocol getPrototype converts endpoint/method descriptor entries into command functions rather than hand-writing each HTTP method.
- Local framework adapters load through initializePlugin(config.framework, 'framework') and expose init/run behavior; reporter configuration accepts custom classes or tuples with options and supports asynchronous synchronization.
- The compiler has package-specific esbuild plugin tables, including protocol type generation, create-wdio template copying, and webdriverio external scripts; BiDi generation derives TypeScript definitions and command methods from CDDL.
Contributor handoff
Begin with the owning package and the smallest relevant lifecycle chain; the inventory and investigation are bounded. Tests and CI were inspected, not executed, and no passing status is asserted. Preserve the distinctions between Node/browser exports, launcher/worker hooks, stub/real sessions, and Classic/BiDi behavior. Proposed validation should remain read-only here and become executable only under appropriate task authorization.
- Use package.json and pnpm-workspace.yaml as the dependency/build authority; tsconfig selects strict NodeNext/ES2022 compilation, and public webdriverio exports require awareness of Node, browser, ESM, and CommonJS surfaces.
- For CLI lifecycle changes, read commands/run.ts, Launcher.run/_runSpecs/_endHandler, and Runner.run first; preserve hook order and the retry-budget message sent before requesting a real session.
- For element behavior, keep changes within the command and relevant lookup/middleware chain; selector, parent, elementId, and BiDi locator fields are functional recovery state rather than incidental metadata.
- Treat Classic and BiDi as explicit branches: findElement excludes iframe/deep-selector cases from its BiDi path, and screenshot options are rejected in Classic but validated and supported in BiDi.
- Do not interpret root build/setup as passive checks: scripts clean artifacts and generate BiDi sources, whose generator can download specification input and overwrite generated TypeScript files.
- If execution is later authorized, select the owning test through the configured Vitest runner first; relevant inspected examples include request.test.ts, launcher.test.ts, and node/saveScreenshot.test.ts. Broader typing, smoke, component, and e2e scripts have distinct prerequisites.
- Tests and CI were inspected, not executed: carry forward the limitations that driver setup is skipped in unit tests, coverage is disabled by default, Preact/misc component commands are bypassed, and cloud CI is main-only.
- Keep publication and deployment outside ordinary edits: npm publishing is manually dispatched and depends on publisher-team authorization, whereas documentation deployment is a separate manually dispatched workflow with cloud credential references.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 251 | docs/config |
| JSON | 169 | docs/config |
| YAML | 40 | docs/config |
| TypeScript | 26 | 74% |
| CSS | 19 | docs/config |
| HTML | 4 | docs/config |
| JavaScript | 4 | 11% |
| Vue | 3 | 9% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (357 files)
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 357 |
website/ | 267 |
.github/ | 40 |
e2e/ | 38 |
examples/ | 31 |
tests/ | 26 |
scripts/ | 5 |
infra/ | 4 |
Docs found: CONTRIBUTING.mdREADME.md
Package
package.json — webdriverio-monorepo, 61 declared dependencies.
@aws-sdk/client-cloudfront@aws-sdk/client-device-farm@aws-sdk/client-s3@aws-sdk/lib-storage@octokit/rest@preact/preset-vite@serenity-js/core@stencil/core@sveltejs/vite-plugin-svelte@types/archiver@types/inquirer@types/lodash.clonedeep
CI & config entrypoints
README.md— Repository readme.github/workflows/authorize-publisher.yml— GitHub Actions workflow.github/workflows/test-xvfb-e2e.yml— GitHub Actions workflow.github/workflows/validate-release-labels.yml— GitHub Actions workflow.github/workflows/cr.yml— GitHub Actions workflow.github/workflows/test-launch.yml— GitHub Actions workflow.github/workflows/publish.yml— GitHub Actions workflow.github/workflows/labeler.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow.github/workflows/test-docs.yml— GitHub Actions workflow
Structural health signals
Average score 8.5/10 across 28 analyzed source files; 1 hotspot surfaced.
website/src/components/Events.tsx— 151 lines, score 6.4 (Deep nesting, Moderate churn)website/src/pages/index.tsx— 334 lines, score 6.9 (Deep nesting, Long function/block)website/src/constants.tsx— 239 lines, score 6.9 (Deep nesting, High churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
dbf0f49713062026-10-01 — feat: upgrade to expect-wdio 7 for multiRemote support (#15838)b148655db4b82026-10-01 — fix(@wdio/utils): do not log short strings as screenshots (#15805)e81b20094c9c2026-10-01 — feat(create-wdio): offer the devtools service in the wizard (#15848)4be5cb2e3eea2026-09-30 — docs(devtools): add a mobile page and follow the examples rename (#15687)f1718757ba442026-09-29 — chore(deps): bump morgan from 1.12.0 to 1.12.1 (#15809)