running-webdriverio-tests

name	running-webdriverio-tests
description	Run WebdriverIO test files from the command line. Use when debugging tests, gathering context about test behavior, or verifying changes resolved an issue.

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.