system

Overview

The system section in Testplane settings is not mandatory.

Use it to:

• enable debug mode for WebDriver;
• change mocha timeouts for tests;
• add some data to the global context that all tests will see;
• specify error types that should close the current browser session permanently instead of trying to reuse it;
• set the number of subprocesses in which tests will run to speed up their execution;
• define the maximum number of browsers available at one time (this can be relevant if you get browsers from a cloud service with such limitations);
• set file extensions among which Testplane will search for tests;
• etc.

Example configuration of the system section:

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    // ...
    system: {
        debug: false,
        mochaOpts: {
            timeout: 60000,
        },
        ctx: {
            /* ... */
        },
        patternsOnReject: [/timeout/i, /timedout/i, /timed out/i],
        workers: 1,
        testsPerWorker: Infinity,
        parallelLimit: 15,
        fileExtensions: [".js", ".ts"],
    },
} satisfies ConfigInput;

System Section Reference

Parameter	Type	Default	Description
debug	boolean	false	Enable/disable debug mode for WebDriver.
expectOpts	ExpectOpts	see below	expect-webdriverio options.
mochaOpts	MochaOpts	see below	Additional options for mocha.
ctx	Record<string, any>	{ }	Context that will be available in all tests via the testplane.ctx method.
patternsOnReject	RegExp[]	[ ]	List of error patterns. The session will be closed if a test fails with an error matching one of the specified patterns. A new session will then be created to avoid infrastructure issues.
workers	number	1	Number of subprocesses that will be launched to run tests.
testsPerWorker	number	Infinity	Maximum number of tests that will be run in one subprocess before the subprocess is restarted.
diffColor	string	"#ff00ff"	Color to display the diff in screenshots.
parallelLimit	number	Infinity	Maximum number of browsers that can be launched simultaneously.
fileExtensions	string[]	[".js", ".mjs", ".ts", ".mts", ".jsx", ".tsx"]	File extensions in which Testplane will search for tests to run.
testRunEnv	nodejs or browser or Array	nodejs	Ability to specify in which environment the tests should be run.

debug

Enables debug mode for WebDriver if set to true. In this mode, detailed information about each command sent to the browser will be output to the console.

Default: false.

expectOpts

Options for expect-webdriverio. Allows changing the timeout and interval between attempts to find an element.

Default:

const defaultExpectOpts = {
    wait: 3000,
    interval: 100,
};

mochaOpts

Additional options for mocha, which are passed to mocha.setup. See the list of available options in the Mocha documentation. Default: { timeout: 60000 }.

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    // ...
    system: {
        mochaOpts: {
            timeout: 60000,
        },
    },
} satisfies ConfigInput;

ctx

Context that will be available in all tests via the testplane.ctx method. Intended for sharing some data between all tests without resorting to using global variables.

Example usage:

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    // ...
    system: {
        ctx: {
            services: ["video", "images"],
        },
    },
} satisfies ConfigInput;

it("awesome test", function () {
    console.log(testplane.ctx); // { services: ['video', 'images'] }
});

tip

Use testplane.ctx in tests instead of global variables.

patternsOnReject

The session will be closed if a test fails with an error matching one of the specified patterns in patternsOnReject. A new session will then be created to avoid infrastructure issues.

Example:

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    // ...
    system: {
        patternsOnReject: [/timeout/i, /timedout/i, /timed out/i],
    },
} satisfies ConfigInput;

workers

Testplane runs all tests in subprocesses to reduce CPU usage for the main process and avoid memory limitations for Node.js. This option sets the number of subprocesses that will be launched to run tests. Default: 1.

testsPerWorker

Maximum number of tests that will be run in one subprocess before the subprocess is restarted. Default: Infinity.

diffColor

Color for displaying the diff in visual checks using the browser.assertView command.

Default: "#ff00ff".

parallelLimit

By default, Testplane launches all browsers simultaneously. Sometimes (e.g., when using cloud services like SauceLabs) you may need to limit the number of browsers that can be launched simultaneously. This option sets that limit. Default: Infinity.

fileExtensions

File extensions in which Testplane will search the file system for tests to run. Default: [".js", ".mjs", ".ts", ".mts", ".jsx", ".tsx"].

testRunEnv

Allows specifying the environment in which tests should be run. The following environments are available:

• nodejs — Testplane will run tests in Node.
• browser — Testplane will run tests in the browser.

When using the browser value, you can specify additional options:

• viteConfig — custom Vite config. You can specify a string — path to the configuration file, an object — UserConfig or a function — with the type (env: ConfigEnv) => UserConfig | Promise<UserConfig>.

Usage examples:

String

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    // ...
    system: {
        testRunEnv: ['browser', { viteConfig: './vite.config.ts' }]
    },
}

Object

testplane.config.ts

import type { ConfigInput } from "testplane";
import viteConfig from './vite.config.ts';

export default {
    // ...
    system: {
        testRunEnv: ['browser', { viteConfig }]
    },
}

Function

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    // ...
    system: {
        testRunEnv: ['browser', {
            viteConfig: (configEnv) => ({
                // ...
            }),
        }],
    },
}