Browsers

What you will learn

How Testplane works with browsers
How to describe browsers in configuration
What browser sources are available: local, Docker, cloud
How to choose the right approach for your task

Introduction

Testplane runs tests in real browsers and is not tied to specific versions or a single browser source.

You describe the required browsers in the browsers section, and the gridUrl parameter determines where to get them from: locally, from a Docker grid (e.g., Selenoid), or from a remote cloud (BrowserStack, Sauce Labs).

General workflow:

Testplane reads the browsers section
For each browser, it takes the gridUrl (common or overridden at the browser level)
Connects to the grid and launches the browser with the specified desiredCapabilities

Usually, all browsers use one source (one gridUrl), but if necessary, it can be set separately for each browser.

Browser Configuration

The browsers section describes which browsers the tests run in.

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

export default {
    browsers: {
        chrome: {
            gridUrl: "local",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
            },
            windowSize: "1920x1080",
            headless: true,
        },

        "chrome-mobile": {
            gridUrl: "local",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "goog:chromeOptions": {
                    mobileEmulation: {
                        deviceName: "iPhone 12 Pro",
                    },
                },
            },
            headless: true,
        },
    },
} satisfies ConfigInput;

The key in browsers (chrome, chrome-mobile) is the logical browser name. It is used in CLI and reports. The name does not limit the actual settings: you can specify any browserName and browserVersion in desiredCapabilities.

The browser version is set in desiredCapabilities.browserVersion. For local browsers, Testplane will download the required version if it is supported.

windowSize: "1920x1080" sets the window size, which is important for screenshot tests.

Headless Mode

The headless: true parameter enables running the browser without a graphical interface.

Important points:

Test behavior is identical: from the test's perspective, a browser with headless: true and headless: false works exactly the same. For example, when running with headless: true, you can still take screenshots, work with the DOM, and execute any commands.
The parameter is required in environments without UI: in environments without a graphical interface (e.g., in CI jobs), you must use headless: true, otherwise you will get errors like cannot open display and similar.

Mobile Emulation

For Chrome, use goog:chromeOptions.mobileEmulation:

const desiredCapabilities = {
    "goog:chromeOptions": {
        mobileEmulation: {
            deviceName: "iPhone 12 Pro",
        },
    },
};

For other supported settings, see the official documentation.

For Firefox, you can emulate a mobile user-agent via moz:firefoxOptions:

const desiredCapabilities = {
    "moz:firefoxOptions": {
        prefs: {
            "general.useragent.override":
                "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15",
            "layout.css.devPixelsPerPx": "3.0",
        },
        args: ["--width=390", "--height=844"],
    },
};

Local Browsers

The easiest way to get started with Testplane. Tests run on browsers and drivers installed on your machine.

Installing Dependencies

Download all browsers and drivers specified in the config that support automatic installation:

npx testplane install-deps

Download only selected browsers (by logical name from config):

npx testplane install-deps chrome-dark

Specify specific versions:

npx testplane install-deps chrome@130 firefox@104

By default, browsers and drivers are downloaded to the .testplane directory in the user's home folder. The path can be changed via the TESTPLANE_BROWSERS_PATH environment variable:

TESTPLANE_BROWSERS_PATH=./node_modules/.testplane npx testplane install-deps

Removing Browsers

Delete the .testplane directory in the home folder
Or delete the directory specified in TESTPLANE_BROWSERS_PATH

Browser Support

Below is a table of supported browsers:

Browser	Auto-download	Driver Auto-download	WebDriver Launch
Chrome	+	+	+
Firefox	+	+	+
Edge	-	+	+
Safari	-	+	+

Supported browser versions depending on OS:

OS	Windows	MacOS	Ubuntu 20	Ubuntu 22	Ubuntu 24
Chrome	73+	73+	73+	73+	73+
Firefox	60+	60+	60+	91+	126+
Edge	*	*	*	*	*
Safari	-	*	-	-	-

* — browser auto-download is not supported, but if the browser is installed by the user, Testplane will use the installed version.

Running Tests

There are two options:

Via the --local CLI option:

npx testplane --local

Via gridUrl: "local" in configuration:

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

export default {
    browsers: {
        chrome: {
            gridUrl: "local",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
            },
            windowSize: "1920x1080",
            headless: true,
        },
    },
} satisfies ConfigInput;

Pros and Cons

Advantages

High test execution speed
No costs for cloud services
Simple setup and easy debugging

Limitations

Limited set of browser versions
OS dependency: screenshots may differ

Local browsers are suitable for development, quick runs, and debugging, but not ideal for screenshot testing across different OSes.

Browsers in Docker Containers

Docker containers provide an isolated and reproducible environment, convenient for CI/CD. Selenoid is often used — a lightweight implementation of Selenium Grid that runs browsers inside containers.

Selenoid:

Manages browsers in Docker containers
Automatically scales containers
Can record video and provides VNC access
Configured via a simple JSON file with browsers

Browser Images

Ready-made images are available on Docker Hub:

selenoid/chrome — Chrome images
selenoid/firefox — Firefox images
selenoid/opera — Opera images

Ready-made images may not include the latest browser versions. To build up-to-date images, use the instructions from the gemini-testing/images repository.

You can track the availability of ready-made fresh images in this issue.

Running a Single Browser in Docker

The easiest way to run a browser in Docker is to use a ready-made image directly:

docker run -it --rm --privileged -p 4444:4444 -p 5900:5900 -e ENABLE_VNC='true' selenoid/chrome:125.0

This command:

Launches a container with Chrome 125.0
Forwards port 4444 for WebDriver
Forwards port 5900 for VNC access
Enables VNC for browser viewing

In the Testplane configuration, specify:

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

export default {
    browsers: {
        chrome: {
            gridUrl: "http://localhost:4444",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
            },
            windowSize: "1920x1080",
            headless: true,
        },
    },
} satisfies ConfigInput;

This approach is convenient for quick testing or debugging in a specific browser version.

Running Selenoid with Multiple Browsers

To work with multiple browsers, use Selenoid: it manages container launches based on a configuration file.

Creating Configuration

Create a browsers.json file describing the required browsers:

browsers.json

{
    "chrome": {
        "versions": {
            "125.0": {
                "image": "selenoid/chrome:125.0",
                "path": "/",
                "port": "4444",
                "shmSize": 2147483648,
                "tmpfs": {
                    "/tmp": "size=512m"
                },
                "volumes": ["/tmp/.X11-unix:/tmp/.X11-unix"]
            }
        }
    },
    "chrome-mobile": {
        "versions": {
            "125.0": {
                "image": "selenoid/chrome-mobile:125.0",
                "path": "/wd/hub",
                "port": "4444",
                "shmSize": 2147483648,
                "tmpfs": {
                    "/tmp": "size=512m"
                },
                "volumes": ["/tmp/.X11-unix:/tmp/.X11-unix"]
            }
        }
    }
}

Starting Selenoid

Start Selenoid, specifying the path to the configuration (in the example, the config is located at /home/selenoid-config/browsers.json):

docker run --rm -d \
  --name selenoid \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /home/selenoid-config:/etc/selenoid/:ro \
  --network=host \
  aerokube/selenoid:latest

Selenoid will automatically launch the required browser containers when receiving requests from Testplane.

Testplane Configuration

The basic configuration is identical to local browsers, only the gridUrl changes:

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

export default {
    browsers: {
        chrome: {
            gridUrl: "http://localhost:4444/wd/hub",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
            },
            windowSize: "1920x1080",
            headless: true,
        },

        "chrome-mobile": {
            gridUrl: "http://localhost:4444/wd/hub",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "goog:chromeOptions": {
                    mobileEmulation: {
                        deviceName: "iPhone 12 Pro",
                    },
                },
            },
            headless: true,
        },
    },
} satisfies ConfigInput;

For more details on Selenoid configuration, see the official documentation.

Selenoid-Specific Options

Selenoid supports additional options via selenoid:options:

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

export default {
    browsers: {
        chrome: {
            gridUrl: "http://localhost:4444/wd/hub",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "selenoid:options": {
                    enableVNC: true,
                    enableVideo: true,
                    enableLog: true,
                },
            },
            windowSize: "1920x1080",
            headless: true,
        },

        "chrome-mobile": {
            gridUrl: "http://localhost:4444/wd/hub",
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "goog:chromeOptions": {
                    mobileEmulation: {
                        deviceName: "iPhone 12 Pro",
                    },
                },
                "selenoid:options": {
                    enableVNC: true,
                    enableVideo: true,
                    enableLog: true,
                },
            },
            headless: true,
        },
    },
} satisfies ConfigInput;

Pros and Cons

Advantages

Browsers behave the same on any machine — whether on a developer's Mac or in Linux CI
Screenshot stability: identical environment guarantees no rendering differences between different OSes
Selenoid can record test run videos and connect to the browser via VNC

Limitations

Need to install Docker and download browser images (plus Selenoid if you use it)
Consumes more resources than local browsers

Docker is well-suited for CI/CD and screenshot testing where stability and reproducibility are important.

Remote Grids

Cloud services (BrowserStack, Sauce Labs, etc.) provide a wide range of browsers, OSes, and real devices for cross-browser testing.

Connection and Authentication

To connect, you need to specify the service's gridUrl and pass credentials via user and key. It is recommended to store them in environment variables.

The basic browser configuration remains the same, only the gridUrl changes and cloud provider-specific options are added:

testplane.config.ts
export default {
    browsers: {
        chrome: {
            gridUrl: "https://hub.browserstack.com/wd/hub",
            user: process.env.BROWSERSTACK_USERNAME,
            key: process.env.BROWSERSTACK_ACCESS_KEY,
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "bstack:options": {
                    os: "Windows",
                    osVersion: "11",
                    projectName: "My Test Project",
                    buildName: "Build 1.0",
                },
            },
            windowSize: "1920x1080",
            headless: true,
        },

        "chrome-mobile": {
            gridUrl: "https://hub.browserstack.com/wd/hub",
            user: process.env.BROWSERSTACK_USERNAME,
            key: process.env.BROWSERSTACK_ACCESS_KEY,
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "goog:chromeOptions": {
                    mobileEmulation: {
                        deviceName: "iPhone 12 Pro",
                    },
                },
                "bstack:options": {
                    os: "Windows",
                    osVersion: "11",
                    projectName: "My Test Project",
                    buildName: "Build 1.0",
                },
            },
            headless: true,
        },
    },
};

Session Customization

Different services have their own options:

BrowserStack (bstack:options)

OS and its version (os, osVersion)
Screen resolution (resolution)
Local testing (local)
Enable logs and debugging (debug, networkLogs, consoleLogs)

Sauce Labs (sauce:options)

Name and build (name, build)
Tags (tags)
Time limits (commandTimeout, idleTimeout, maxDuration)
Video and logs (recordVideo, recordLogs)

Timeouts and Debugging

Cloud services strictly limit the execution time of a single command, session idle time, and maximum session duration.

For debugging, the following are available:

Session logs
Video of each run
VNC or similar for browser viewing
Network logs

Pros and Cons

Advantages

Wide selection of browsers, versions, and operating systems
No need to maintain your own infrastructure
Built-in debugging tools: logs, video, network traces

Limitations

Cost of usage with a large number of runs
Dependency on network quality and possible latency
Strict session execution time limits

Cloud grids are suitable for cross-browser and mobile testing when you need wide platform coverage without the costs of your own infrastructure.

How to Choose a Browser Source

It is recommended to choose one browser source for the entire project (or for each test pack if you split them into groups). Choose the approach that covers your main needs:

Local Browsers for Most Projects

If you don't use screenshot tests and speed of execution is important (e.g., for development and debugging), local browsers are the simplest and fastest option. They don't require additional infrastructure and work directly on your machine.

Docker for Stable Screenshots

When screenshot stability between different machines and operating systems is important, and you're ready to work with Docker images, use Docker. An identical environment guarantees identical screenshots on any machine.

Cloud Grids for Scaling

If you need screenshot stability, high parallelism for thousands of tests, or testing on many browser and OS combinations, cloud grids are suitable. You won't have to maintain your own infrastructure, and you'll have access to a wide range of browsers and devices. The downside is the cost with a large number of runs.

tip

For development and debugging, you can use local browsers (run with --local), even if Docker or cloud is used in CI. This will speed up iterations when writing tests.

Debugging

There are two ways to enable verbose logs.

Via configuration:

testplane.config.ts
export default {
    browsers: {
        // ... your browsers
    },
    system: {
        debug: true,
    },
};

Via environment variables (with limited webdriverio logging level):

testplane_system_debug=true WDIO_LOG_LEVEL=error npx testplane --local -b chrome

Browsers

Introduction​

Browser Configuration​

Headless Mode​

Mobile Emulation​

Local Browsers​

Installing Dependencies​

Removing Browsers​

Browser Support​

Running Tests​

Pros and Cons​

Advantages​

Limitations​

Browsers in Docker Containers​

Browser Images​

Running a Single Browser in Docker​

Running Selenoid with Multiple Browsers​

Creating Configuration​

Starting Selenoid​

Testplane Configuration​

Selenoid-Specific Options​

Pros and Cons​

Advantages​

Limitations​

Remote Grids​

Connection and Authentication​

Session Customization​

Timeouts and Debugging​

Pros and Cons​

Advantages​

Limitations​

How to Choose a Browser Source​

Local Browsers for Most Projects​

Docker for Stable Screenshots​

Cloud Grids for Scaling​

Debugging​

Introduction

Browser Configuration

Headless Mode

Mobile Emulation

Local Browsers

Installing Dependencies

Removing Browsers

Browser Support

Running Tests

Pros and Cons

Advantages

Limitations

Browsers in Docker Containers

Browser Images

Running a Single Browser in Docker

Running Selenoid with Multiple Browsers

Creating Configuration

Starting Selenoid

Testplane Configuration

Selenoid-Specific Options

Pros and Cons

Advantages

Limitations

Remote Grids

Connection and Authentication

Session Customization

Timeouts and Debugging

Pros and Cons

Advantages

Limitations

How to Choose a Browser Source

Local Browsers for Most Projects

Docker for Stable Screenshots

Cloud Grids for Scaling

Debugging