Set Up a WebdriverIO Project in TypeScript
On this page
The fastest way to a working WebdriverIO project is the official starter, create-wdio. It asks a handful of questions, installs the packages that match your answers, writes a wdio.conf.ts, and can generate an example spec with page objects. This chapter runs it, walks through what it created, and trims the config to the parts you need.
Run the starter#
Make a folder and run the wizard inside it:
mkdir wdio-course && cd wdio-course
npm init wdio@latest .
npm init wdio runs the create-wdio package. The interactive wizard asks what you want to test (choose E2E testing of web applications), where the browsers run (on my local machine for now; chapter 6 moves to the cloud), which framework (Mocha), whether to use TypeScript (yes), whether to generate example tests and page objects (yes), and which reporter (spec).
Every question also has a flag, which is handy when you want the same project twice or in a script. This is the exact command the course project was created with:
npm init wdio@latest . -- --yes --framework mocha --typescript \
--browsers chrome --reporters spec --generate-test-files --page-objects
--yes accepts the defaults for everything you did not pass. The -- separates npm's own options from the ones for create-wdio. Run npx create-wdio --help to see all flags.
When the wizard finishes, the folder looks like this:
wdio-course/
package.json
tsconfig.json
wdio.conf.ts
test/
specs/test.e2e.ts
pageobjects/page.ts
pageobjects/login.page.ts
pageobjects/secure.page.ts
Recent versions also write an AGENTS.md and a .agents/ folder with instructions for AI coding assistants. They do not affect test runs; keep or delete them.
What got installed#
package.json lists the pieces of a WebdriverIO project, each a separate package:
{
"type": "module",
"devDependencies": {
"@types/node": "^26.6.6",
"@wdio/cli": "^10.2.0",
"@wdio/globals": "^10.2.0",
"@wdio/local-runner": "^10.2.0",
"@wdio/mocha-framework": "^10.2.0",
"@wdio/spec-reporter": "^10.2.0",
"expect-webdriverio": "^8.1.0"
},
"scripts": {
"wdio": "wdio run ./wdio.conf.ts"
}
}
-
@wdio/cliis thewdiocommand and the runner. -
@wdio/local-runnerstarts the worker processes on your machine. -
@wdio/mocha-frameworkadapts Mocha'sdescribe/itto the runner. Jasmine and Cucumber adapters exist too. -
@wdio/globalsexportsbrowser,$,$$andexpect, so specs can import them explicitly. -
expect-webdriverioprovides the retrying matchers you will use in chapter 4. -
@wdio/spec-reporterprints the readable pass/fail output.
Keep the @wdio/* packages on the same version. Mixing a 10.x runner with a 9.x framework adapter produces confusing errors.
You do not install ChromeDriver. When a capability asks for a local browser, WebdriverIO downloads a matching driver (and, if needed, a browser build) the first time and caches it.
After npm update, @wdio/cli is on 10.2.0 but @wdio/mocha-framework stayed on 9.x, and the runner fails before any test starts. What is the right fix?
The runner, framework adapter, reporters and services are released together and expect each other's versions. ChromeDriver is downloaded automatically, and changing the framework does not fix a version mismatch.
The config, trimmed#
The generated wdio.conf.ts is about 300 lines, most of them comments that document every option and hook. They are worth reading once. For the course, replace the file with the parts that matter:
export const config: WebdriverIO.Config = {
runner: 'local',
tsConfigPath: './tsconfig.json',
specs: ['./test/specs/**/*.ts'],
maxInstances: 4,
capabilities: [{
browserName: 'chrome'
}],
logLevel: 'warn',
baseUrl: 'https://the-internet.herokuapp.com',
waitforTimeout: 10000,
connectionRetryTimeout: 120000,
connectionRetryCount: 3,
framework: 'mocha',
reporters: ['spec'],
mochaOpts: {
ui: 'bdd',
timeout: 60000
}
}
What each option does:
-
specsis a glob of spec files. Each matching file runs in its own worker. -
capabilitiesis the list of browsers. One entry here means every spec runs in Chrome. Chapter 6 adds more. -
maxInstancescaps how many workers run at the same time. -
logLevelcontrols the runner's own logging. The starter setsinfo, which prints every WebDriver request;warnkeeps the output readable. Chapter 9 turns it back up. -
baseUrllets you writebrowser.url('/login')instead of the full address. -
waitforTimeoutis how long element commands andexpectmatchers wait (chapter 3). -
mochaOpts.timeoutis how long a single test may take before Mocha fails it. It has to be longer than any wait inside the test.
The tsconfig.json the starter wrote already lists the WebdriverIO types (@wdio/globals/types, expect-webdriverio, @wdio/mocha-framework), so your editor knows browser, $ and the matchers. There is no build step: the runner compiles TypeScript on the fly.
Run the example spec#
npm run wdio
Chrome opens, logs into the practice site and closes again. The spec reporter prints:
[chrome 157.0.8103.78 mac #0-0] Running: chrome (v157.0.8103.78) on mac
[chrome 157.0.8103.78 mac #0-0] Session ID: c98789f42cb5b31d65c4db8ec83b59c4
[chrome 157.0.8103.78 mac #0-0]
[chrome 157.0.8103.78 mac #0-0] » test/specs/test.e2e.ts
[chrome 157.0.8103.78 mac #0-0] My Login application
[chrome 157.0.8103.78 mac #0-0] ✓ should login with valid credentials
[chrome 157.0.8103.78 mac #0-0]
[chrome 157.0.8103.78 mac #0-0] 1 passing (2.4s)
Spec Files: 1 passed, 1 total (100% completed) in 00:00:06
The #0-0 prefix is the worker id: capability index, then spec index. With several browsers and spec files you will see #1-2 and so on, which tells you which browser ran which file.
To run one file, pass --spec:
npx wdio run wdio.conf.ts --spec test/specs/test.e2e.ts
A test waits up to 30 seconds for a slow report to load, and Mocha keeps failing it with "Timeout of 20000ms exceeded". Which setting do you change?
The Mocha timeout limits the whole test, so it must leave room for the waits inside it. connectionRetryTimeout is about HTTP requests to the driver, and a shorter element timeout would just fail the wait sooner.
Where this project goes next#
Rename test/specs/test.e2e.ts to login.e2e.ts; chapter 5 rebuilds it with better page objects. The next three chapters add selectors.e2e.ts, waiting.e2e.ts and assertions.e2e.ts next to it, so by chapter 6 you have four spec files to send to the cloud.