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.mdreferences/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=tracewhen 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 () { ... });
Skip specific tests
it.skip("should return -1 unless present", function () { ... });
Remember to revert .only/.skip changes after debugging.