TypeScript Setup

You can write tests using TypeScript to get auto-completion and type safety.

You will need typescript and ts-node installed as devDependencies, via:

npm

$ npm install typescript ts-node --save-dev

Yarn

$ yarn add typescript ts-node --dev

pnpm

$ pnpm add typescript ts-node --save-dev

WebdriverIO will automatically detect if these dependencies are installed and will compile your config and tests for you. Ensure to have a tsconfig.json in the same directory as you WDIO config. If you need to configure how ts-node runs please use the environment variables for ts-node or use wdio config's autoCompileOpts section.

Configuration

You can provide custom ts-node options through the environment (by default it uses the tsconfig.json in the root relative to your wdio config if the file exists):

# run wdio testrunner with custom options
TS_NODE_PROJECT=./config/tsconfig.e2e.json TS_NODE_TYPE_CHECK=true wdio run wdio.conf.ts

The minimum TypeScript version is v4.0.5.

Framework Setup

And your tsconfig.json needs the following:

tsconfig.json

{
    "compilerOptions": {
        "types": ["node", "@wdio/globals/types"]
    }
}

Please avoid importing webdriverio or @wdio/sync explicitly. WebdriverIO and WebDriver types are accessible from anywhere once added to types in tsconfig.json. If you use additional WebdriverIO services, plugins or the devtools automation package, please also add them to the types list as many provide additional typings.

Framework Types

Depending on the framework you use, you will need to add the types for that framework to your tsconfig.json types property, as well as install its type definitions. This is especially important if you want to have type support for the built-in assertion library expect-webdriverio.

For instance, if you decide to use the Mocha framework, you need to install @types/mocha and add it like this to have all types globally available:

Mocha

tsconfig.json

{
    "compilerOptions": {
        "types": ["node", "@wdio/globals/types", "@wdio/mocha-framework"]
    }
}

Jasmine

tsconfig.json

{
    "compilerOptions": {
        "types": ["node", "@wdio/globals/types", "@wdio/jasmine-framework"]
    }
}

Cucumber

tsconfig.json

{
    "compilerOptions": {
        "types": ["node", "@wdio/globals/types", "@wdio/cucumber-framework"]
    }
}

Services

If you use services that add commands to the browser scope you also need to include these into your tsconfig.json. For example if you use the @wdio/devtools-service ensure that you add it to the types as well, e.g.:

tsconfig.json

{
    "compilerOptions": {
        "types": [
            "node",
            "@wdio/globals/types",
            "@wdio/mocha-framework",
            "@wdio/devtools-service"
        ]
    }
}

Adding services and reporters to your TypeScript config also strengthen the type safety of your WebdriverIO config file.

Type Definitions

When running WebdriverIO commands all properties are usually typed so that you don't have to deal with importing additional types. However there are cases where you want to define variables upfront. To ensure that these are type safe you can use all types defined in the @wdio/types package. For example if you like to define the remote option for webdriverio you can do:

import type { Options } from '@wdio/types'

const config: Options.WebdriverIO = {
    hostname: 'http://localhost',
    port: '4444' // Error: Type 'string' is not assignable to type 'number'.ts(2322)
    capabilities: {
        browserName: 'chrome'
    }
}

Missing Types

When using Node 20 or above, wdio runs ts-node with different settings as this is required in order to keep things running. These settings can cause your custom types not to be loaded, if this happens there are a few ways you can fix this, of which the easiest I will show below.

Using ts-node's environment variables

TS_NODE_FILES=true wdio run ./wdio.conf.ts

Using tsconfig

{
  "ts-node": {
    "files": true
  },
}

For more information checkout the (ts-node documentation)[https://typestrong.org/ts-node/docs/troubleshooting#missing-types].

Tips and Hints

Compile & Lint

To be entirely safe, you may consider following the best practices: compile your code with TypeScript compiler (run tsc or npx tsc) and have eslint running on pre-commit hook.