Skip to main content
Version: v8

Typescript and ESM

TypeScript in Testplane​

Testplane supports TypeScript out of the box — you don’t need to set up additional tools for transpilation, you can start writing tests right away:

describe("test examples", () => {
    it("Open the main page and check the title", async ({ browser }) => {
        await browser.url("https://testplane.io/");

        const title = await browser.getTitle();
        expect(title).toContain("Testplane");
    });
});

And you can specify .ts files directly in the config:

// .testplane.config.ts
export default {
    sets: {
        desktop: {
            files: ["tests/**/*.ts"],
        },
    },
};

Transpilation options​

Testplane automatically uses @swc/core for transpilation if this package is installed in the project, otherwise, it uses esbuild, which is already included in Testplane.

:::warning Warning Type checking must be implemented separately using tsc and a config file. :::

If automatic transpilation doesn’t suit your project’s specifics, you can disable it using the TS_ENABLE=false environment variable and set it up manually.

To pass the required loader when setting it up manually, use the --require option, for example:

-r ts-node/register

Working with import aliases​

Many projects use path aliases in tsconfig.json:

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@components/*": ["src/components/*"],
            "@utils/*": ["src/utils/*"],
            "@fixtures/*": ["tests/fixtures/*"]
        }
    }
}

However, the TypeScript compiler can resolve these paths only at compile time. At runtime, Node.js is unaware of these aliases, and you’ll get an error:

 Cannot find module '@components/Button'.

Resolving paths at runtime​

Install the tsconfig-paths package:

npm install --save-dev tsconfig-paths

Use the --require option:

npx testplane -r tsconfig-paths/register

For a more detailed introduction to tsconfig-paths, visit the package documentation website.

Config typing​

Testplane exports types for the configuration, for example:

import type { ConfigInput } from "testplane";

export default {
    // ...
} satisfies ConfigInput;

The satisfies operator checks whether a value is compatible with the specified type while preserving the original type of that value.

Extending browser command types​

Testplane supports custom commands with TypeScript:

import "webdriverio"; // Any import can be used here — it doesn’t have to be webdriverio

declare global {
    declare namespace WebdriverIO {
        interface Browser {
            customCommand: (arg: any) => Promise<void>;
        }
    }
}

You can read more about this in the custom commands guide.

Working with ESM​

System limitations​

To work with ESM, you’ll need Node.js version v22.0.0, v20.17.0, or higher. Interoperation of ESM and CommonJS code is possible thanks to a Node's feature, described in the article.

On this page