Skip to main content

Installation and Setup

System requirements​

To start working with Testplane, install Node.js version 18.0 or higher.

Installation​

To run the Testplane installer using npm, execute the following command:

npm init testplane@latest YOUR_PROJECT_PATH

To configure the project in interactive mode with additional parameters (package manager selection, plugin installation), specify the -v option.

After running the installation command, the following set of files and folders will appear in the project directory:

node_modules
testplane-tests
    example.testplane.ts
    ts.config.json
package-lock.json
package.json
testplane.config.ts

Setup​

The testplane.config.ts file contains a basic set of settings for running tests:

testplane.config.ts
import { setupBrowser } from "@testplane/testing-library";
import type { WdioBrowser } from "testplane";

export default {
    gridUrl: "local",
    baseUrl: "http://localhost",
    pageLoadTimeout: 20000,
    httpTimeout: 20000,
    testTimeout: 90000,
    resetCursor: false,
    sets: {
        desktop: {
            files: ["testplane-tests/**/*.testplane.(t|j)s"],
            browsers: ["chrome", "firefox"],
        },
    },
    browsers: {
        chrome: {
            headless: true,
            desiredCapabilities: {
                browserName: "chrome",
            },
        },
        firefox: {
            headless: true,
            desiredCapabilities: {
                browserName: "firefox",
            },
        },
    },
    prepareBrowser: (browser: WdioBrowser) => {
        setupBrowser(browser);
    },
    plugins: {
        "html-reporter/testplane": {
            enabled: true,
            path: "testplane-report",
            defaultView: "all",
            diffMode: "3-up-scaled",
        },
    },
} satisfies import("testplane").ConfigInput;

Key configuration parameters​

  • gridUrl — where to run browsers: "local" for local execution or a URL for Selenium Grid or cloud (e.g., BrowserStack, Sauce Labs).
  • sets — test groups for different browsers (e.g., a test set for desktop Chrome or Firefox and a set for mobile Safari). Learn more: Sets reference.
  • testTimeout — maximum test execution time in milliseconds; the test is aborted after exceeding this limit.
  • pageLoadTimeout — maximum page load wait time.
  • browsers — browser configuration; headless: true — run without UI. Learn more: Browsers.
  • prepareBrowser — hook before tests; in the config above it calls setupBrowser(browser) and adds Testing Library methods.
  • plugins — plugins; in the config above html-reporter for interactive reports (screenshots, logs, debugging). Learn more: HTML Reporter.

For a complete list of configuration parameters, see the configuration reference.

To download the browsers described in the config separately from running Testplane itself, execute the command:

npx testplane install-deps

Without running this command beforehand, missing browsers will be automatically downloaded the first time Testplane is launched.

First run​

After installation and setup, run the test example that was created automatically:

npx testplane

What happens during the first run​

Testplane will automatically perform the following actions:

  1. Download browsers: if you haven't run install-deps, Testplane will download Chrome and Firefox
  2. Run the test: execute the example from testplane-tests/example.testplane.ts
  3. Generate a report: create an HTML report in the testplane-report/ folder

Viewing results​

After the tests finish, open the interactive report:

npx testplane gui

The command will start a local server and open the report in your browser. In the interface you will see:

  • List of passed tests
  • Execution statistics
  • Screenshots (if the test uses assertView)
  • Execution logs

Expected outcome​

If everything is configured correctly, you will see:

✔ test examples › docs search test [chrome] - 3.2s
✔ test examples › docs search test [firefox] - 3.5s

Total: 2 Passed: 2 Failed: 0 Skipped: 0 Retries: 0

For the tests to pass successfully, they need access to testplane.io.

What's next?​

Now that Testplane is set up and running, you can:

On this page