Skip to main content

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 install 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 your wdio.conf.ts, e.g.:

wdio.conf.ts
export const config = {
    // ...
    autoCompileOpts: {
        autoCompile: true,
        // see https://github.com/TypeStrong/ts-node#cli-and-programmatic-options
        // for all available options
        tsNodeOpts: {
            transpileOnly: true,
            project: './tsconfig.json'
        }
    }
}

Or apply them through the environment:

# run wdio testrunner with custom tsconfig.json location
TS_NODE_PROJECT=./.config/tsconfig.json 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:

tsconfig.json
{
    "compilerOptions": {
        "types": ["node", "@wdio/globals/types", "@wdio/mocha-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'
    }
}

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.