Running WebdriverIO Tests

Main Command

npx wdio

Config is in wdio.conf.js by default.

Project Context Files

Before selecting run commands, read project cache files when available:

.webdriverio-skills/project-context.md
.webdriverio-skills/project-context.json
.webdriverio-skills/custom-rules.md
references/website-analysis/<target>/website-analysis.md

Use these files to prefer project-approved scripts, configs, environment flags, and server targets.

Use website analysis references to prioritize high-impact route/component test runs first.

Resolve <target> as lowercase site host (prefer explicit URL or project baseUrl host), fallback unknown-target.

If files are missing or stale, run managing-project-customizations first.

Duration

Tests take 20 seconds to 5 minutes. Do not treat a slow test as a failure.

Selecting Tests to Run

Prefer package.json scripts discovered in project context when they exist (e.g. npm run test:e2e, npm run test:wdio:debug) before using raw npx wdio.

By spec file

# Single file
npx wdio --spec=test/specs/home.js

# Multiple files
npx wdio --spec=test/specs/home.js --spec=test/specs/register.js

By suite

Suite names are defined in the WebdriverIO config file under the suites property.

npx wdio --suite=auth

Excluding files

npx wdio --exclude=test/specs/home.js

Can be mixed with --spec or --suite.

Key CLI Options

Option	Description
`--spec`	Run specific spec file(s) or wildcard
`--suite`	Run a named suite from wdio.conf.js
`--exclude`	Exclude spec file(s) from run
`--logLevel`	`trace`, `debug`, `info`, `warn`, `error`, `silent`
`--bail`	Stop after N failures (default: 0 = run all)
`--maxInstances`	Number of parallel browser instances (2–10)
`--baseUrl`	Override base URL for `browser.url()` calls
`--repeat`	Repeat specs/suites N times

Log Level

Use --logLevel=trace when debugging (maximum output)
Use default (info) when confirming tests pass (less noise)

npx wdio --logLevel=trace --spec=test/specs/home.js

Bail

npx wdio --bail=1

Max Instances

npx wdio --maxInstances=3

Base URL

Changes the base server used with relative paths (e.g., browser.url('./homepage.html')).

npx wdio --baseUrl=https://example.com/

Isolating Individual Tests (Mocha)

Edit the test file temporarily to add .only or .skip.

Run only specific tests

describe.only("Form Fields", function () { ... });
it.only("should submit form", function () { ... });

Mocha docs: exclusive tests

Skip specific tests

it.skip("should return -1 unless present", function () { ... });

Mocha docs: inclusive tests

Remember to revert .only/.skip changes after debugging.

running-webdriverio-tests