Environment:Webdriverio Webdriverio Node Runtime Environment

Knowledge Sources	WebdriverIO Node.js
Domains	Infrastructure, Runtime
Last Updated	2026-02-12 01:00 GMT

Overview

Node.js >= 18.20.0 runtime environment with pnpm package manager and TypeScript 5.x for building and running WebdriverIO v9.

Description

This environment defines the core runtime requirements for WebdriverIO v9.24.0. The project is a Node.js monorepo managed by pnpm (v10.12.4) with TypeScript compilation targeting ES2022. All packages in the monorepo share the same minimum Node.js version requirement of 18.20.0, though the project's own development uses Node.js v24 (via `.nvmrc`). The module system is ESM-first (`"type": "module"` in package.json) with CommonJS compatibility via `.cjs` entry points.

Usage

Use this environment for any interaction with the WebdriverIO framework — running tests, developing plugins, or contributing to the project. This is the mandatory prerequisite for all WebdriverIO implementations including the Remote_Function, ConfigParser_Class, Launcher_Class, and all other core modules.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	All platforms supported; Safari driver macOS only
Node.js	>= 18.20.0	v24 used for development (via .nvmrc)
Package Manager	pnpm >= 8.15.3	Project specifies pnpm 10.12.4
Disk	500MB+	Monorepo with many packages; node_modules can be large

Dependencies

System Packages

`node` >= 18.20.0
`pnpm` >= 8.15.3 (or `npm` / `yarn` for consuming packages)
`git` (for development contributions)

Language Packages

Core (always required):

`webdriverio` = 9.24.0
`@wdio/cli` = 9.24.0 (test runner CLI)

Test Framework (choose one):

`@wdio/mocha-framework` (uses `mocha` ^10.3.0)
`@wdio/jasmine-framework` (uses `jasmine` ^5.0.0)
`@wdio/cucumber-framework` (uses `@cucumber/cucumber` ^10.3.1)

Browser Runner (for component testing):

`@wdio/browser-runner` (uses `vite` ^5.4.10)

Optional:

`puppeteer-core` >= 22.x (for Chrome DevTools Protocol features)
`typescript` >= 3.8.3 (for TypeScript test files)
`expect-webdriverio` ^5.3.4 (assertion library)

Credentials

No credentials are required for the base runtime environment. Cloud service credentials are documented in Environment:Webdriverio_Webdriverio_Cloud_Service_Credentials.

Quick Install

# Install WebdriverIO with the test runner
npm init wdio@latest ./

# Or install manually
npm install webdriverio @wdio/cli @wdio/local-runner @wdio/mocha-framework @wdio/spec-reporter

# For TypeScript support
npm install typescript tsx

Code Evidence

Node.js version requirement from `packages/webdriverio/package.json`:

{
  "engines": {
    "node": ">=18.20.0"
  }
}

Package manager specification from root `package.json`:

{
  "packageManager": "pnpm@10.12.4",
  "type": "module"
}

Node.js development version from `.nvmrc`:

v24

TypeScript configuration from root `tsconfig.json`:

{
  "compilerOptions": {
    "target": "es2022",
    "module": "NodeNext",
    "moduleResolution": "node16"
  }
}

Supported config file extensions from `packages/wdio-config/src/constants.ts:102-104`:

export const SUPPORTED_FILE_EXTENSIONS = [
    '.js', '.jsx', '.mjs', '.mts', '.es6', '.ts', '.tsx', '.feature', '.coffee', '.cjs'
]

Common Errors

Error Message	Cause	Solution
`No named export object called "config" found`	Config file uses wrong export syntax	Use `export const config = { ... }` (ESM) or `module.exports.config = { ... }` (CJS)
`SyntaxError: Cannot use import statement outside a module`	Node.js treating ESM as CJS	Add `"type": "module"` to package.json or use `.mjs` extension
`Error: unsupported engine`	Node.js version below 18.20.0	Upgrade Node.js to >= 18.20.0

Compatibility Notes

ESM vs CJS: WebdriverIO v9 is ESM-first. CommonJS entry points are provided via `.cjs` files for backward compatibility.
TypeScript: Config files can be `.ts` — WebdriverIO uses `tsx` internally for TypeScript transpilation. Minimum TypeScript 3.8.3 but 5.x recommended.
pnpm vs npm/yarn: While the monorepo uses pnpm, consuming packages work with any Node.js package manager.
Windows: Fully supported. Chrome requires unique `user-data-dir` per worker in parallel execution to avoid "directory already in use" errors.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment