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.

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.

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.

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.
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. Does not work with the deprecated plugin hermione-passive-browsers.

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.

meta

Additional data that will be returned by the getMeta() command. Data can also be added "on the fly" using the setMeta() command: before, during, or after the test run.

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.

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.