Getting Started
Set up WebdriverIO in an existing or new project with one command, then run your first test. The configuration wizard asks what you want to test (web, mobile, desktop or VS Code extensions), which framework and reporters to use, and installs everything for you.
These are the docs for WebdriverIO v10. Still on v9? Use the v9 documentation or follow the v10 migration guide.
Point it at https://webdriver.io/llms.txt or connect the docs MCP server at https://webdriver.io/mcp. See WebdriverIO for Coding Agents.
Initiate a WebdriverIO Setup​
The WebdriverIO Starter Toolkit adds a complete WebdriverIO setup to an existing or new project. In the root directory of an existing project, run:
- NPM
- Yarn
- pnpm
- bun
npm init wdio@latest .
or if you want to create a new project:
npm init wdio@latest ./path/to/new/project
yarn create wdio .
or if you want to create a new project:
yarn create wdio ./path/to/new/project
pnpm create wdio@latest .
or if you want to create a new project:
pnpm create wdio@latest ./path/to/new/project
bun create wdio@latest .
or if you want to create a new project:
bun create wdio@latest ./path/to/new/project
This single command downloads the WebdriverIO CLI tool and runs a configuration wizard that helps you to configure your test suite.
The wizard will prompt a set questions that guides you through the setup. You can pass a --yes parameter to pick a default set up which will use Mocha with Chrome using the Page Object pattern.
- NPM
- Yarn
- pnpm
- bun
npm init wdio@latest . -- --yes
yarn create wdio . --yes
pnpm create wdio@latest . --yes
bun create wdio@latest . --yes
Answer the wizard with flags​
Every question in the wizard has a command line flag. A flag answers its question and the wizard asks only the rest. Together with --yes, the wizard uses the defaults for the rest and never prompts, which is what a coding agent or a CI job needs:
# Cucumber in JavaScript, with the spec and JUnit reporters
npm init wdio@latest . -- --yes --framework cucumber --no-typescript --reporters spec,junit
# Firefox and Edge instead of Chrome
npm init wdio@latest . -- --yes --browsers firefox,edge
# An Android app with Appium
npm init wdio@latest . -- --yes --mobile-environment android
# React component tests
npm init wdio@latest . -- --yes --runner component --preset react
# Write the config, but install the dependencies yourself
npm init wdio@latest . -- --yes --no-npm-install
With Yarn, pnpm and bun, pass the flags without the -- separator, e.g. pnpm create wdio@latest . --yes --framework cucumber.
The most common flags:
| Flag | Values |
|---|---|
--runner | e2e (default), component, desktop, vscode, roku |
--framework | mocha (default), jasmine, cucumber, serenity-mocha, serenity-jasmine, serenity-cucumber |
--typescript / --no-typescript | TypeScript is the default when the project has a tsconfig.json |
--browsers | Comma-separated list of chrome (default), firefox, safari, edge |
--mobile-environment | android, ios |
--backend | local (default), saucelabs, browserstack, experitest, grid, other |
--preset | lit, vue, svelte, solid, stencil, react, preact, other, with --runner component |
--desktop-framework | electron, tauri, dioxus, macos, with --runner desktop |
--reporters, --services, --plugins | Comma-separated short names, e.g. --reporters spec,junit --services visual |
--agent-support / --no-agent-support | Write the AGENTS.md section and the wdio-session skill (on by default) |
--npm-install / --no-npm-install | Install the dependencies (on by default) |
npm init wdio@latest -- --help lists every flag, the values it accepts and the question it answers. Boolean flags take a --no- prefix. The same flags work with npx wdio config.
The wizard checks each flag against your setup. An unknown value, a flag for a question it would not ask, or a value it would not offer for your setup stops it with exit code 2 before it writes any file:
Error: --preset does not apply to this setup. UI framework of your components (with --runner component).
Install CLI Manually​
You can also add the CLI package to your project manually via:
npm i --save-dev @wdio/cli
npx wdio --version # prints e.g. `8.13.10`
# run configuration wizard
npx wdio config
Run Test​
You can start your test suite by using the run command and pointing to the WebdriverIO config that you just created:
npx wdio run ./wdio.conf.js
If you like to run specific test files you can add a --spec parameter:
npx wdio run ./wdio.conf.js --spec example.e2e.js
or define suites in your config file and run just the test files defined by in a suite:
npx wdio run ./wdio.conf.js --suite exampleSuiteName
Run in a script​
If you would like to use WebdriverIO as an automation engine in Standalone Mode within a Node.JS script you can also directly install WebdriverIO and use it as a package, e.g. to generate a screenshot of a website:
loading...
Note: all WebdriverIO commands are asynchronous and need to be properly handled using async/await.
Record tests​
WebdriverIO provides tools to help you get started by recording your test actions on screen and generate WebdriverIO test scripts automatically. See Recorder tests with Chrome DevTools Recorder for more information.
System Requirements​
You’ll need Node.js installed.
- Install at least v22.19.0 or higher as this is the oldest supported LTS version
- Only releases that are or will become an LTS release are officially supported
If Node is not currently installed on your system, we suggest utilizing a tool such as NVM or Volta to assist in managing multiple active Node.js versions. NVM is a popular choice, while Volta is also a good alternative.
Watch the Introduction​
More videos are on the official YouTube channel.
Next Steps​
- Pick your platform: Web Browsers, Mobile Apps, Desktop Apps or Extensions & Editors
- Learn how to select elements and write assertions
- Configure the test runner in
wdio.conf.ts - Get help on Discord
