browsers

Overview

The browsers section is mandatory in Testplane settings. It specifies all the browsers in which the tests will run.

Setup

This section has the following format:

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    browsers: {
        "<browser-id>": {
            desiredCapabilities: {
                browserName: "<browser-name>",
                // ...
            },
            // ...
        },
    },
} satisfies ConfigInput;

Where <browser-id> is the name of the browser used for its identification.

To avoid repeating the same settings for different browsers, you can set all the default values you need at the root of the Testplane config. For example:

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    sessionsPerBrowser: 10,
    browsers: {
        chrome: {
            /* ... */
        },
        firefox: {
            // ...
            sessionsPerBrowser: 5,
        },
    },
} satisfies ConfigInput;

In this example, the value 10 will be used for the sessionsPerBrowser option for chrome, and 5 for firefox.

Main browser settings

Parameter	Type	Default	Description
`desiredCapabilities`	`DesiredCapabilities`	N/A	Required parameter. Specifies the properties that the browser must have. Used by WebDriver, see DesiredCapabilities.
`gridUrl`	`string`	`"http://localhost` `:4444/wd/hub"`	Selenium grid URL.
`baseUrl`	`string`	`"http://localhost"`	Base URL of the service being tested.
`browserWSEndpoint`	`string`	`null`	Websocket endpoint for connecting to the browser via Chrome DevTools Protocol (CDP).
`automationProtocol`	`string`	`"webdriver"`	Protocol for communication with the browser. See WebDriver vs CDP.
`sessionEnvFlags`	`SessionEnvFlags`	`{}`	Environment flags setting the protocol to be used in the created browser session.
`windowSize`	`string \| WindowSize`	`null`	Browser window size.
`headless`	`boolean \| "new" \| "old"`	depends on browser	Allows running the browser in headless mode.

desiredCapabilities

Required parameter. Specifies the properties that the browser must have.

The format of the desiredCapabilities object is defined by the WebDriver standard.

In addition to standard options, some tools provide specific settings in their namespaces.

Browser-specific options:

Chrome, goog:chromeOptions — ChromeDriver options documentation
Firefox, moz:firefoxOptions — Geckodriver documentation
Edge, ms:edgeOptions — EdgeDriver documentation

Grid-specific browser options:

Sauce Labs, sauce:options — documentation
BrowserStack, bstack:options — documentation
TestingBot, tb:options — documentation

Options specific to some automation tools:

Appium, appium:* — documentation
Selenoid, selenoid:options — documentation

Example of an extended desiredCapabilities setting:

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    browsers: {
        chrome: {
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "goog:chromeOptions": {
                    args: ["--hide-scrollbars", "--headless=new"],
                },
            },
        },
    },
} satisfies ConfigInput;

gridUrl

Grid URL (the address where ChromeDriver/Selenium Standalone/Sauce Labs/etc. listens).

Default: http://localhost:4444/wd/hub.

info

You can also use value "local" in order to use local browsers, managed by Testplane. Read more in guide How to launch Testplane in the local browser.

baseUrl

Base URL of the service being tested. Allows for more convenient use of the browser.url commands:

if the target address starts with /, baseUrl without the path part will be added at the beginning.
if the target address does not start with /, the entire baseUrl will be added at the beginning.
it is important whether / exists (or not). See more.

Default: http://localhost.

browserWSEndpoint

Websocket endpoint for connecting to the browser via Chrome DevTools Protocol (CDP). For example, you specify browserWSEndpoint: "ws://YOUR_HOST/devtools", to which the browser session identifier will be added at the end: ws://YOUR_HOST/devtools/12345, where 12345 is the session identifier.

Default value: null. It means that Testplane will try to determine the websocket endpoint automatically.

automationProtocol

Protocol for communication with the browser. Available values: webdriver and devtools. See also WebDriver vs CDP. Default: webdriver.

Removed in Testplane 9

Starting from Testplane 9, the value "devtools" has been removed. It caused a number of hard-to-reproduce errors that never occurred under "webdriver", and the underlying WebdriverIO has also dropped its devtools automation protocol. The only supported value is now "webdriver".

To launch tests in a locally installed browser, use gridUrl: "local" instead — Testplane will automatically download the required browser and driver and start it via WebDriver. See the Running on Local Browsers blog post for a step-by-step guide.

This change does not affect the Chrome DevTools Protocol itself — you can still use CDP from your tests, see the How to Use Chrome DevTools Protocol guide.

sessionEnvFlags

Environment flags set the protocols that will be used in the created browser session. By default, environment flags are automatically set according to the specified desiredCapabilities. However, in rare cases, they may have incorrect values and can be explicitly set using this option.

Available flags:

Flag	Protocols
`isW3C`	WebDriverProtocol or by default JsonWProtocol
`isChrome`	ChromiumProtocol
`isMobile`	MJsonWProtocol and AppiumProtocol
`isSauce`	Sauce Labs specific commands
`isSeleniumStandalone`	Special Selenium commands when running tests in Selenium Grid or using Selenium Standalone Server.

For example:

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    browsers: {
        "chrome-phone": {
            // ...
            sessionEnvFlags: {
                isMobile: true,
            },
        },
    },
} satisfies ConfigInput;

windowSize

Browser window size. If not specified, the window size will depend on WebDriver. Can be specified as a string, for example, 800x1000 or as an object with width and height keys with integer values.

For example:

const browserOptions = {
    windowSize: "800x1000",
};

and

const browserOptions = {
    windowSize: {
        width: 800,
        height: 1000,
    },
};

are equivalent.

warning

Setting the resolution for the Opera browser or for mobile browsers does not work as these browsers only use fullscreen mode.

headless

Allows managing the browser's headless mode (without visible browser display). Can be set as a boolean value, and from Chrome version 112, can be set as a string "new" | "old". More about the new headless mode — in Chrome blog.

Default: null (determined on the browser side).

Timeouts

Parameter	Type	Default	Description
`waitTimeout`	`number`	`3000`	Timeout for events on the web page, in ms.
`waitInterval`	`number`	`500`	Interval for events on the web page, in ms.
`httpTimeout`	`number`	`30000`	Timeout for any requests to the Selenium server, in ms.
`urlHttpTimeout`	`number`	= httpTimeout	Timeout for the /url request to the Selenium server, in ms.
`pageLoadTimeout`	`number`	`20000`	Timeout for the full page load, in ms.
`sessionRequestTimeout`	`number`	= httpTimeout	Timeout for the browser session request, in ms.
`sessionQuitTimeout`	`number`	`5000`	Timeout for ending the session, in ms.
`testTimeout`	`number`	`null`	Timeout for running the test, in ms. If the value is not set, the general timeout for all browsers will be used, which is set with the system.mochaOpts.timeout setting.

waitTimeout

Timeout for events on the web page, in milliseconds. Default: 3000 ms (3 seconds).

Applied in the waitUntil command, which is used in all waitFor* commands when searching for a specified element on the page.

For example, when executing the browser.$('.element').click() command, the $('element') subcommand will, by default, wait for the element's existence up to 3000 ms before clicking it.

waitInterval

Interval for events on the web page, in milliseconds. Default: 500 ms.

Applied in the waitUntil command, which is used in all waitFor* commands when searching for a specified element on the page.

For example, when executing the browser.$('.element').click() command, the $('element') subcommand will, by default, check for the existence of the element every 500 ms.

httpTimeout

Timeout for any requests to the Selenium server, in milliseconds. Default: 30000 ms.

urlHttpTimeout

Timeout for the /url request to the Selenium server, in milliseconds. Sometimes, when opening a link on the server side, a lot of logic is executed in middleware, causing the link to take a long time to open. To avoid increasing the timeout for all commands due to this, Testplane allows you to set a separate timeout for the /url request.

pageLoadTimeout

Timeout for the full page load, in milliseconds. Default: 20000 ms.

sessionRequestTimeout

Timeout for the browser session request, in milliseconds. By default, it takes the value of the httpTimeout setting.

sessionQuitTimeout

Timeout for ending the session, in milliseconds. Default: 5000 ms.

testTimeout

Timeout for running the test, in milliseconds. When used for a test suite, it will apply to all tests and hooks within that suite.

If the value is not set, the general timeout for all browsers, set with the system.mochaOpts.timeout setting, will be used.

Running Tests

Parameter	Type	Default	Description
`sessionsPerBrowser`	`number`	`1`	Number of sessions that will be run simultaneously for a particular browser.
`testsPerSession`	`number`	`Infinity`	How many tests can be run sequentially in one browser session. This parameter limits the reuse of the session to prevent test failures due to browser degradation, and has nothing to do with parallel test execution.
`retry`	`number`	`0`	How many times to retry a failing test.
`shouldRetry`	`(data: FailedTestData) => boolean`	see description	Function that determines if a retry is needed. By default, a function is set that returns true if retry > 0 and false if retry == 0.
`strictTestsOrder`	`boolean`	`false`	Guarantee strict order of tests. If true, the API function testplane.readTests will always return the same result.
`passive`	`boolean`	`false`	Allows making the browser passive. In passive browsers, tests do not run by default. Available since testplane@8.16.0. Warning: it currently has issues, read below.
`openAndWaitOpts`	`OpenAndWaitOpts`	see description	Allows setting default options for the `browser.openAndWait` command.
`isolation`	`boolean`	`true` for Chrome 93+	Enables isolation mode using browser contexts.

sessionsPerBrowser

Number of sessions that will be run simultaneously for a particular browser. Default: 1.

testsPerSession

This parameter specifies how many tests can be run sequentially in one browser session. It can be useful to limit the reuse of the session. If the same browser session is used many times for running different tests, at some point the browser may start to degrade. This can affect the test run, leading to failures. Once the limit of tests is reached, the session will be closed and a new session will start.

Default: Infinity. This means the session will be reused an infinite number of times. However, in real operations, there may be limitations from the grid on which the browsers are running. For example, the grid may limit the maximum lifetime of a session, and then the number of tests that can be run within a session will be determined by its lifetime.

warning

Be careful: this parameter has nothing to do with parallel test execution.

retry

How many times to retry a test if it fails. Default: 0.

shouldRetry

Function that determines if a retry is needed. Should return a Boolean value. By default, a function is set that returns true if there are still retries available, and false if the retry limit for the test has been reached (see retry setting).

The argument of this function is an object with the following fields:

interface FailedTestData {
    ctx: {
        id(): string;
        browserId: string;
        sessionId: string;
    };
    retriesLeft: number;
    error?: Error;
}

strictTestsOrder

This option guarantees strict order of reading tests. Default: false.

passive

warning

Available since testplane@8.16.0.

This option currently doesn't work well with html-reporter. For now, we recommend to keep using the hermione-passive-browsers plugin. Note that the plugin and this option must not be used together. We're already working on a fix.

Allows making the browser passive. In passive browsers, tests do not run by default. Using the helper testplane.also.in, you can enable a test or suite before it is run.

Default: false.

openAndWaitOpts

Allows setting options to be used when calling the browser.openAndWait command.

Default:

const defaultOpenAndWaitOpts = {
    waitNetworkIdle: true,
    waitNetworkIdleTimeout: 500,
    failOnNetworkError: true,
    ignoreNetworkErrorsPatterns: [],
};

isolation

Enables running tests in isolated browser contexts. This means that testsPerSession can be set to Infinity to run all tests in one session and significantly speed up the test run.

Works starting from Chrome 93 and higher.

Default: true for Chrome 93 and higher, false otherwise.

Test and Failure Information

Parameter	Type	Default	Description
`meta`	`Record<string, any>`	N/A	Additional data that will be returned by the getMeta() command.
`takeScreenshotOnFails`	`ScreenshotOnFails`	`{ testFail: true, assertViewFail: true }`	Determines whether to take a screenshot of the browser page (Page Screenshot) on test failure, as well as on assertView command failure.
`takeScreenshotOnFailsMode`	`"viewport" \| "fullpage"`	`"fullpage"`	Mode for taking a screenshot upon test failure.
`takeScreenshotOnFailsTimeout`	`number`	`5000`	Timeout for taking a screenshot of the browser page (Page Screenshot) upon test failure, in ms.
`saveHistoryMode`	`"all" \| "none" \| "onlyFailed"`	`"all"`	Save the history of all commands executed.

takeScreenshotOnFails

This option is set as an object:

interface ScreenshotOnFails {
    testFail: boolean;
    assertViewFail: boolean;
}

These keys determine whether to take a screenshot of the browser page (Page Screenshot) upon test failure and upon assertView command failure, respectively. In the case of testFail, all test failures except those due to assertView commands are taken into account.

Default: { testFail: true, assertViewFail: true }.

takeScreenshotOnFailsMode

Mode for taking a screenshot of the browser page upon test failure. Available values: viewport and fullpage:

viewport — take a screenshot of the current viewport.
fullpage — take a screenshot of the entire browser page.

Default: fullpage.

takeScreenshotOnFailsTimeout

Timeout for taking a screenshot of the browser page upon test failure, in milliseconds. Default: 5000 ms.

saveHistoryMode

warning

Available since hermione@7.

Save the history of all commands executed. Default: all.

Available values:

all — history is enabled.
none — history is disabled.
onlyFailed — history is saved only for failed tests.

Some plugins may rely on this history, such as html-reporter.

History is accessible from the following events — TEST_END, TEST_PASS, TEST_FAIL — via payload. Example of a plugin that uses the history:

exports = testplane => {
    testplane.on(testplane.events.TEST_PASS, async test => {
        console.log(test.history);
    });
};

Preparing for Screenshot Taking

Parameter	Type	Default	Description
`calibrate`	`boolean`	`false`	Perform calibration before taking a screenshot.
`orientation`	`string`	`null`	Browser window orientation to set before each test run.
`waitOrientationChange`	`boolean`	`true`	Wait for actual orientation change.
`resetCursor`	`boolean`	`true`	Move cursor to point (0, 0) in body coordinates before each test run.
`screenshotsDir`	`string \| (test: Test) => string`	`"./testplane/screens"`	Folder for saving reference screenshots with the assertView command. By default testplane/screens relative to the working directory: process.cwd().

calibrate

Perform calibration before taking a screenshot. In some WebDriver implementations, when taking a screenshot, UI elements of the browser itself may appear on the image. Calibration helps solve this issue. Default: false.

orientation

Browser window orientation to set before each test run. Available values: landscape, portrait, null. Default: null.

Which value to choose for orientation?

It depends on the orientation in which most of your tests are executed. If the majority of tests are run in landscape mode, set the orientation value to landscape. Then, tests that require portrait orientation will set their desired orientation themselves. The orientation option will ensure that all other tests will be run with the landscape orientation automatically without needing to set it in each test.

waitOrientationChange

Wait for actual orientation change. Default: true. When set to true, testplane ensures that the setOrientation command will complete only after the orientation is actually changed to the specified one.

resetCursor

Move the cursor to point (0, 0) in body coordinates before each test run. Default: true. It may be needed in cases where the default cursor position affects test execution. For example, when a tooltip (hint) pops up because of the cursor, which "spoils" the screenshot being taken.

tip

It is recommended to reset the cursor for desktop browsers and not for mobile ones.

screenshotsDir

Folder for saving reference screenshots with the assertView command. By default, it is the testplane/screens folder relative to the working directory: process.cwd(). The value of this option can also be a function that takes one argument — the test instance within which the assertView command was called, for example:

const browserOptions = {
    screenshotsDir: test => `tests/screenshots/${test.parent.title}`,
};

Taking and Comparing Screenshots

Parameter	Type	Default	Description
`tolerance`	`number`	`2.3`	Maximum allowed CIEDE2000 difference between colors.
`antialiasingTolerance`	`number`	`4`	Sets the sensitivity for detecting antialiasing, which will be ignored when comparing screenshots.
`compareOpts`	`CompareOpts`	see below	Options for image comparison.
`buildDiffOpts`	`BuildDiffOpts`	see below	Options for building the diff (image showing differences between screenshots).
`assertViewOpts`	`AssertViewOpts`	see below	Default options for the assertView command.
`compositeImage`	`boolean`	`true`	Allows testing elements that do not fit within the viewport height.
`screenshotMode`	`"auto" \| "fullpage" \| "viewport"`	`"auto"`	Screenshot mode.
`screenshotDelay`	`number`	`0`	Delay before taking the screenshot, in ms.

tolerance

Maximum allowed CIEDE2000 difference between colors. Used only in non-strict mode. Default: 2.3. Starting from the value 2.3, the color difference becomes perceptible to the human eye. The smaller the value, the stricter the screenshot comparison.

It is not recommended to increase the tolerance value globally. Instead, try setting tolerance for specific test suites or states.

Here's how to take a screenshot for a specific state with an individual tolerance setting:

it("some-test", async function (browser) {
    await browser.assertView("some-state", ".selector1", { tolerance: 10 });
    await browser.assertView("another-state", ".selector1");
});

antialiasingTolerance

Sets the sensitivity for detecting antialiasing, which will be ignored when comparing screenshots.

Read more about this option in the looks-same package.

compareOpts

Additional options for image comparison. See the list of available options in the looks-same documentation.

Default:

const defaultCompareOpts = {
    shouldCluster: false,
    clustersSize: 10,
    stopOnFirstFail: false,
};

buildDiffOpts

Additional options for building the diff (image showing the differences between screenshots). See the list of available options in the looks-same documentation. Default:

const defaultBuildDiffOpts = {
    ignoreAntialiasing: true,
    ignoreCaret: true,
};

assertViewOpts

Options for the assertView command to take and compare screenshots, which will be used by default. They can be overridden when calling the assertView command.

Available assertView options:

Option	Type	Description
ignoreElements	Array or String	Elements (specified as selectors) that will be ignored when comparing screenshots. Ignoring is implemented by painting the listed elements black. In the case of a single element, the parameter can be specified as a string.
tolerance	Number	Sensitivity to color differences.
antialiasingTolerance	Number	Sensitivity to antialiasing.
allowViewportOverflow	Boolean	By default, Testplane throws an error if an element is outside the viewport boundaries. This parameter disables boundary checking, allowing screenshots of elements that do not fit within the viewport. Only the parts of the element that fit within the viewport will be visible in the screenshot. However, if compositeImage is set to true, parts of the element that are below the viewport will also be visible in the screenshot. Similarly, if captureElementFromTop is set to true, parts of the element that are above the viewport will also be included in the screenshot.
captureElementFromTop	Boolean	Capture a screenshot of the element from the very top. If the element is outside the viewport, it will be scrolled into view.
compositeImage	Boolean	If the element does not fit within the viewport, enabling this option will take multiple screenshots of different parts of the element sequentially, and then stitch them together into one image to display the entire element.
screenshotDelay	Number	Delay in milliseconds before taking a screenshot. This can be useful when there are elements on the page that use animation, or a scrollbar that does not disappear immediately and ends up in the resulting screenshot.
selectorToScroll	String	Selector to scroll. This can be useful when you need to take a screenshot of a modal window that does not fit on the screen. Otherwise, without specifying the selector, the scroll will be applied to the window object, and the background will scroll, leaving the popup window in place.
disableAnimation	Boolean	Disable animations and transitions when taking a screenshot. Default is `true` starting from version `8.0.0`.
ignoreDiffPixelCount	`${number}%` or Number	Percentage of pixels to ignore in the diff. Useful for ignoring very small diffs. Default is `0`. Available starting from version `8.2.0`.
waitForStaticToLoadTimeout	Number	Timeout for `waitForStaticToLoad` command, which is automatically called before taking screenshot. Waiting is disabled, if value is set to `0`. Default is `5000`. Available starting from version `8.32.0`.

Default:

const defaultAssertViewOpts = {
    ignoreElements: [],
    captureElementFromTop: true,
    allowViewportOverflow: false,
    disableAnimation: true,
    ignoreDiffPixelCount: 0,
};

compositeImage

Allows testing elements that do not fit within the viewport height. Default: true. If the tested block is taller than the viewport, the images of several viewports are stitched together into one image.

screenshotMode

Screenshot mode. Default: auto.

Possible values:

"auto" — the mode will be determined automatically.
"fullpage" — a screenshot of the entire page will be taken.
"viewport" — only the viewport will be captured in the screenshot.

By default, the viewport mode is set for android browsers to bypass a bug in Chromium.

In desktop browsers, it is possible to get an image of the entire page out of the box, without manually stitching images of separate viewports into one large screenshot. However, on mobile devices, there is no such functionality.

screenshotDelay

Delay in milliseconds before taking the screenshot. Default: 0 ms. The delay can be helpful in cases where the page contains elements using animation or a scrollbar that does not disappear immediately and affects the resulting screenshot.

Request and Response Parameters

Parameter	Type	Default	Description
`agent`	`object`	`null`	Allows setting custom agents for http, https, http2 requests.
`headers`	`Record<string, string>`	`null`	Allows setting custom headers to be sent with each WebDriver request.
`transformRequest`	`TransformRequestFn`	`null`	Allows intercepting and transforming http-request options before the request is sent to WebDriver.
`transformResponse`	`TransformResponseFn`	`null`	Allows intercepting and transforming http-response received from WebDriver.
`strictSSL`	`boolean`	`null`	Whether the SSL certificate must be valid.

agent

Allows setting custom agents for http, https, http2 requests. Default: null (in this case, default http agents from the got package will be used).

headers

Allows setting custom headers to be sent with each WebDriver request. Default: null. See also in the WebDriverIO documentation.

warning

These headers are not sent in requests from the browser where the tests are executed. They are sent only in requests to WebDriver.

transformRequest

Allows intercepting and transforming http-request options before the request is sent to WebDriver. Default: null. If a function is passed, the RequestOptions object will be passed as the first argument. The function should return the modified RequestOptions.

Function type:

type TransformRequestFn = (req: RequestOptions) => RequestOptions;

By default, this function is used to generate the X-Request-ID header. This header has the format ${FIRST_X_REQ_ID}__${LAST_X_REQ_ID}, where:

FIRST_X_REQ_ID - a unique UUID for each test (different for each retry), allows finding all requests related to the specific test run;
LAST_X_REQ_ID - a unique UUID for each request to the browser within one test, in combination with FIRST_X_REQ_ID it allows finding the specific request.

Example value: 2f31ffb7-369d-41f4-bbb8-77744615d2eb__e8d011d8-bb76-42b9-b80e-02f03b8d6fe1.

The X-Request-ID header can be useful for debugging problematic requests if you use your own browser grid and save request logs.

You can generate X-Request-ID in your format using transformRequest. Example:

const transformRequest = req => {
    req.headers["X-Request-ID"] = "my_x_req_id";

    return req;
};

transformResponse

Allows intercepting and transforming the http-response received from WebDriver. Default: null. If a function is passed, the Response object will be passed as the first argument, and the RequestOptions as the second argument. The function should return the modified Response.

Function type:

type TransformResponsetFn = (res: Response, req: RequestOptions) => Response;

strictSSL

Whether the SSL certificate must be valid. If not set, the default value from WebDriverIO will be used.

Cloud Settings

The following settings may be useful if you want to run your testplane tests in browsers of cloud services.

An example of such a cloud service could be SauceLabs, which can provide you with both desktop and mobile browsers for running tests.

Parameter	Type	Default	Description
`user`	`string`	`null`	Username in the cloud service.
`key`	`string`	`null`	Access key or secret key for accessing the cloud service.
`region`	`string`	`null`	Allows selecting different data centers in the cloud service.
`headless`	`string`	`null`	Allows running a headless browser in the cloud service.

user

Username in the cloud service. Default: null.

key

Access key or secret key for accessing the cloud service. Default: null.

region

Allows selecting different data centers in the cloud service. Default: null.

headless

Allows running a headless browser in the cloud service. Default: null.

Time Travel

These settings allow you to configure test run snapshot recording for subsequent playback in the player. To learn more about Time Travel capabilities, see the Time Travel guide.

Parameter	Type	Default	Description
`timeTravel`	`string \| TimeTravelSettings`	`"off"`	Time Travel settings.

timeTravel

Time Travel settings. Default: "off".

For quick setup, you can pass a string — one of the recording modes (TimeTravelMode). The full configuration looks like this:

enum TimeTravelMode {
    // Snapshot recording is enabled for all runs
    On = "on",
    // Snapshot recording is disabled
    Off = "off",
    // Snapshot recording is enabled for all retries (first run is not considered a retry)
    RetriesOnly = "retries-only",
    // Snapshot recording is enabled for all runs, but only snapshots for the last failed run are saved
    // For example:
    // - if the test was run once and failed, the snapshot will be recorded.
    // - if the test was run 5 times and failed all 5 times, the snapshot for the 5th retry will be recorded.
    // - if the test was run 2 times and passed both times, no snapshots will be recorded.
    LastFailedRun = "last-failed-run",
}

interface TimeTravelConfig {
    mode: TimeTravelMode;
}

Example of a valid configuration:

import { TimeTravelMode } from "@testplane/testplane";

export = {
    timeTravel: {
        mode: TimeTravelMode.RetriesOnly,
    },
};

Selectivity

This section allows you to configure Testplane's selective test execution, avoiding the launch of tests for which nothing has changed.

The section has the following parameters:

Parameter	Type	Default	Description
`enabled`	`SelectivityMode`	`SelectivityMode.Disabled`	Available modes: `SelectivityMode.Disabled`, `SelectivityMode.Enabled`, `SelectivityMode.ReadOnly`, `SelectivityMode.WriteOnly`. In `ReadOnly` mode unchanged tests are skipped, but selectivity dump is not updated after successful run. In `WriteOnly` mode all tests are run, but selectivity dump is updated after successful run.
`sourceRoot`	`string`	`""`	Configures the path to the root of the source code files.
`testDependenciesPath`	`string`	`".testplane/selectivity"`	The path to the directory where test dependency data will be saved.
`compression`	`"none" \| "gz" \| "br" \| "zstd"`	`"gz"`	The compression type applied to the test dependency data.
`disableSelectivityPatterns`	`string[]`	`[]`	A list of patterns. If a file matching one of these patterns is changed, selectivity will be disabled.
`mapDependencyRelativePath`	`null \| (dependency: { scope: "browser" \| "testplane", reason: "browser-css-import" \| "browser-js-coverage" \| "testplane-js-import" \| "testplane-assert-view-reference", relativePath: string }) => string \| boolean \| void`	`null`	Callback, which accepts test dependency info and maps its path to another path. The dependency object contains `scope` (`"browser"` or `"testplane"`), `relativePath` in POSIX style, and `reason` — one of `"browser-css-import"`, `"browser-js-coverage"`, `"testplane-js-import"`, or `"testplane-assert-view-reference"`, indicating how the dependency was collected. Return a mapped `string` path to remap, `true` to keep the original path unchanged, or a falsy value (`false`, `undefined`, `void`) to filter the dependency out completely.
`mapSourceMapUrl`	`null \| (assetInfo: { type: "css" \| "js", sourceUrl: string, sourceMapUrl: string }) => string \| boolean \| void`	`null`	Callback to filter or remap source map URLs before they are fetched. Return a mapped `string` URL to remap, `true` to keep the original URL unchanged, or a falsy value to skip the asset entirely (both the script/style and its source map will be ignored).
`saveIncompleteDumpOnFail`	`boolean`	`false`	When `true`, selectivity dump is saved even if some tests failed. This allows you to later rerun only the failed tests with `--last-failed-only` to complete the dump without re-running the entire suite. See the guide on recovering from a failed selectivity run.
`reportPath`	`string`	`""`	If set, selectivity JSON-report will be saved to specified file path.

`mapDependencyRelativePath` examples

Ignore Next.js internal dependencies

{
    selectivity: {
        enabled: true,
        mapDependencyRelativePath({relativePath}) {
            if (relativePath.startsWith("turbopack://")) {
                return;
            }

            return relativePath;
        },
    }
}

Usage with @testplane/storybook plugin

{
    selectivity: {
        enabled: true,
        mapDependencyRelativePath({relativePath}) {
            // Testplane storybook autogenerated tests
            if (relativePath.includes("/testplane-storybook-autogenerated/")) {
                return;
            }

            // Storybook fake dependencies
            if (relativePath === "storybook-stories.js" || relativePath === "storybook-config-entry.js") {
                return;
            }

            return relativePath;
        },
    }
}

`mapSourceMapUrl` examples

Filter out third-party scripts

{
    selectivity: {
        enabled: true,
        mapSourceMapUrl({ type, sourceUrl, sourceMapUrl }) {
            // Skip analytics and tracking scripts
            if (sourceUrl.includes("analytics") || sourceUrl.includes("tracking")) {
                return false;
            }

            return true;
        },
    }
}

Remap source map URL to a local server

{
    selectivity: {
        enabled: true,
        mapSourceMapUrl({ type, sourceUrl, sourceMapUrl }) {
            // Redirect source map fetching to a local server
            if (sourceMapUrl.startsWith("https://cdn.example.com/")) {
                return sourceMapUrl.replace("https://cdn.example.com/", "http://localhost:3000/");
            }

            return true;
        },
    }
}

info

You should not specify node_modules in disableSelectivityPatterns, as this will cause a significant slowdown. Instead, it is recommended to specify Testplane configuration files and the application's backend source code.

stateOpts

Available from testplane v8.40.0

Default settings for state commands.

You can set parameters once and then use state commands (saveState, restoreState, getState) without specifying options. However, if you explicitly provide parameters for a command, they will have the highest priority.

Parameter	Type	Default	Description
`stateOpts`	`StateOpts`	`undefined`	Default options for state commands.

type StateOpts = {
    path?: string;
    cookies?: boolean;
    localStorage?: boolean;
    sessionStorage?: boolean;
    cookieFilter?: (cookie: Cookie) => boolean;
    keepFile?: boolean;
};

Example of a valid configuration:

export = {
    stateOpts: {
        path: "stateDump.json",
    },
};

browsers

Overview​

Setup​

Main browser settings​

desiredCapabilities​

gridUrl​

baseUrl​

browserWSEndpoint​

automationProtocol​

sessionEnvFlags​

windowSize​

headless​

Timeouts​

waitTimeout​

waitInterval​

httpTimeout​

urlHttpTimeout​

pageLoadTimeout​

sessionRequestTimeout​

sessionQuitTimeout​

testTimeout​

Running Tests​

sessionsPerBrowser​

testsPerSession​

retry​

shouldRetry​

strictTestsOrder​

passive​

openAndWaitOpts​

isolation​

Test and Failure Information​

meta​

takeScreenshotOnFails​

takeScreenshotOnFailsMode​

takeScreenshotOnFailsTimeout​

saveHistoryMode​

Preparing for Screenshot Taking​

calibrate​

orientation​

waitOrientationChange​

resetCursor​

screenshotsDir​

Taking and Comparing Screenshots​

tolerance​

antialiasingTolerance​

compareOpts​

buildDiffOpts​

assertViewOpts​

compositeImage​

screenshotMode​

screenshotDelay​

Request and Response Parameters​

agent​

headers​

transformRequest​

transformResponse​

strictSSL​

Cloud Settings​

user​

key​

region​

headless​

Time Travel​

timeTravel​

Selectivity​

mapDependencyRelativePath examples​

Ignore Next.js internal dependencies​

Usage with @testplane/storybook plugin​

mapSourceMapUrl examples​

Filter out third-party scripts​

Remap source map URL to a local server​

stateOpts​

Overview

Setup

Main browser settings

desiredCapabilities

gridUrl

baseUrl

browserWSEndpoint

automationProtocol

sessionEnvFlags

windowSize

headless

Timeouts

waitTimeout

waitInterval

httpTimeout

urlHttpTimeout

pageLoadTimeout

sessionRequestTimeout

sessionQuitTimeout

testTimeout

Running Tests

sessionsPerBrowser

testsPerSession

retry

shouldRetry

strictTestsOrder

passive

openAndWaitOpts

isolation

Test and Failure Information

meta

takeScreenshotOnFails

takeScreenshotOnFailsMode

takeScreenshotOnFailsTimeout

saveHistoryMode

Preparing for Screenshot Taking

calibrate

orientation

waitOrientationChange

resetCursor

screenshotsDir

Taking and Comparing Screenshots

tolerance

antialiasingTolerance

compareOpts

buildDiffOpts

assertViewOpts

compositeImage

screenshotMode

screenshotDelay

Request and Response Parameters

agent

headers

transformRequest

transformResponse

strictSSL

Cloud Settings

user

key

region

headless

Time Travel

timeTravel

Selectivity

`mapDependencyRelativePath` examples

Ignore Next.js internal dependencies

Usage with @testplane/storybook plugin

`mapSourceMapUrl` examples

Filter out third-party scripts

Remap source map URL to a local server

stateOpts