---
title: Run .side Files with selenium-side-runner | TestingBot
description: The IDE is where you build and debug tests. To run them every night,
  on every deploy or in several browsers, you need them on the command line, without…
source_url:
  html: https://testingbot.com/resources/courses/selenium-ide/run-side-files-with-selenium-side-runner
  md: https://testingbot.com/resources/courses/selenium-ide/run-side-files-with-selenium-side-runner.md
---

Course

[Selenium IDE: Codeless Test Automation](https://testingbot.com/resources/courses/selenium-ide)

Chapter 7 of 10

1. [1 Selenium IDE Tutorial: Codeless Test Automation](https://testingbot.com/resources/courses/selenium-ide)
2. [2 Install Selenium IDE and Record Your First Test](https://testingbot.com/resources/courses/selenium-ide/install-and-record-your-first-test)
3. [3 Commands, Targets and Locators in Selenium IDE](https://testingbot.com/resources/courses/selenium-ide/commands-targets-and-locators)
4. [4 Assertions, Verifications and Waits in Selenium IDE](https://testingbot.com/resources/courses/selenium-ide/assertions-verifications-and-waits)
5. [5 Variables, store and Control Flow in Selenium IDE](https://testingbot.com/resources/courses/selenium-ide/variables-and-control-flow)
6. [6 Reusing Tests and Organising Suites in Selenium IDE](https://testingbot.com/resources/courses/selenium-ide/reusing-tests-and-suites)
7. [7 Run .side Files with selenium-side-runner](https://testingbot.com/resources/courses/selenium-ide/run-side-files-with-selenium-side-runner)
8. [8 Run Selenium IDE Tests on the TestingBot Grid](https://testingbot.com/resources/courses/selenium-ide/run-on-testingbot)
9. [9 Export Selenium IDE Tests to Code, and When to Graduate](https://testingbot.com/resources/courses/selenium-ide/export-to-code)
10. [10 Knowledge check](https://testingbot.com/resources/courses/selenium-ide/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 7 of 10 Beginner 7 min read 2 quick checks Updated Nov 2026 

# Run .side Files with selenium-side-runner
On this page
1. [Install](https://testingbot.com#install)
2. [Run the project](https://testingbot.com#run-the-project)
3. [Capabilities: which browser, how](https://testingbot.com#capabilities-which-browser-how)
4. [Options you will use](https://testingbot.com#options-you-will-use)
5. [A configuration file: .side.yml](https://testingbot.com#a-configuration-file-side-yml)
6. [Reports, screenshots and exit codes](https://testingbot.com#reports-screenshots-and-exit-codes)

The IDE is where you build and debug tests. To run them every night, on every deploy or in several browsers, you need them on the command line, without anyone pressing Play. That is what `selenium-side-runner` does: it reads a `.side` file and plays its suites through Selenium WebDriver in real browsers, and it exits with an error code when a test fails, which is all a CI system needs. This chapter runs the course project locally in Chrome and Firefox.

## Install[#](https://testingbot.com#install)

The runner is an npm package. It needs Node.js 22 or newer; its README asks for 22.23.4 or later on the 22 line, or Node.js 24 or 26.

```bash
npm install -g selenium-side-runner
selenium-side-runner --version
```

```
4.1.0-beta.3
```

That is the version npm installed on 13 November 2026: the 4.1.0 betas are published under the default `latest` tag. To keep a team on the same version, install it into a project folder instead (`npm install --save-dev selenium-side-runner@4.1.0-beta.3`) and run it with `npx selenium-side-runner`.

**You do not need to install browser drivers.** Older guides tell you to `npm install -g chromedriver geckodriver`. The current runner uses selenium-webdriver 4.52, whose Selenium Manager finds or downloads the right driver for the browser on your machine the first time. You need the browsers themselves: Chrome, Firefox or Edge.

## Run the project[#](https://testingbot.com#run-the-project)

From the folder that contains `the-internet.side`:

```bash
selenium-side-runner the-internet.side
```

Without options the runner uses Chrome. It runs every suite in the file and prints a summary per test. This is from one of our runs:

```
PASS ../node_modules/selenium-side-runner/dist/main.test.js (24.623 s)
  Running project the-internet
    Running suite Smoke
      ✓ Running test Log in with valid credentials (2929 ms)
      ✓ Running test Wrong password shows an error (2629 ms)
      ✓ Running test Check both checkboxes (2104 ms)
      ✓ Running test Pick an option from the dropdown (2210 ms)
      ✓ Running test Wait for content that loads later (7426 ms)
      ✓ Running test Log in and log out (3034 ms)
    Running suite Variables and control flow
      ✓ Running test Store and reuse values (2216 ms)
      ✓ Running test Add and remove elements (1983 ms)

Test Suites: 1 passed, 1 total
Tests: 8 passed, 8 total
```

The "PASS" and "Test Suites: 1" lines come from Jest, the test runner `selenium-side-runner` uses underneath. They always say one test suite, whatever the number of Selenium IDE suites in the file.

## Capabilities: which browser, how[#](https://testingbot.com#capabilities-which-browser-how)

`-c` (or `--capabilities`) passes WebDriver capabilities as `key=value` pairs separated by spaces. Dots create nested values and square brackets create lists:

```bash
# Firefox, without a visible window
selenium-side-runner -c "browserName=firefox moz:firefoxOptions.args=[-headless]" the-internet.side

# Chrome, without a visible window
selenium-side-runner -c "browserName=chrome goog:chromeOptions.args=[headless=new]" the-internet.side
```

We ran the project in both: eight of eight passed in headless Chrome and in headless Firefox, with the same file.

## Options you will use[#](https://testingbot.com#options-you-will-use)

| Option | What it does |
| --- | --- |
| `--steps` | prints every command as it finishes, with ✓, ✕ or the error |
| `-f, --filter <regex>` | runs only the suites whose name matches, for example `--filter Smoke` |
| `--base-url <url>` | replaces the project's base URL, for example a staging server; absolute URLs in `open` are not changed |
| `-t, --timeout <ms>` | how long element commands wait for their element (15000 by default); the command-line version of the IDE's Step Timeout |
| `-w, --max-workers <n>` | how many tests may run at once, for suites marked Parallel (chapter 5) |
| `-r, --retries <n>` | re-runs a failed test up to n times |
| `-o, --output-directory <dir>` | writes a JSON report of the run |
| `-z, --screenshot-failure-directory <dir>` | saves a screenshot of the page when a test fails |
| `-s, --server <url>` | runs the browsers on a remote Selenium server or grid instead of locally (chapter 7) |
| `-i, --interactive` | lists the tests and lets you pick one; new in 4.1.0-beta.3, needs a terminal, not for CI |

`--steps` is the one to reach for when something fails. It shows exactly which command broke and why:

```
info: ✓ Fallback demo › open | /login
info: ✕ Fallback demo › type | id=user-name | tomsmith: Operation timed out during type:id=user-name:tomsmith
info: Finished test Fallback demo Failure
```

A word on `--retries`: a test that passes on the second attempt is a flaky test, and retries hide it. Use them as a short-term measure while you fix the cause, and look at what is being retried. Chapter 3 and the [flaky tests course](https://testingbot.com/resources/courses/flaky-tests/retries-and-quarantine) cover why.

The project was recorded against production. You want the nightly run to test `https://staging.example.com` without editing the file. What do you add?

 `-c "baseUrl=https://staging.example.com"` `--server https://staging.example.com` `--base-url https://staging.example.com`, which works for every `open` with a relative path

`--base-url` replaces the project's base URL. `--server` is where the browsers run, not the site under test, and `baseUrl` is not a WebDriver capability. Steps that open an absolute URL keep going to production, which is why recordings should use relative paths.

## A configuration file: .side.yml[#](https://testingbot.com#a-configuration-file-side-yml)

Long command lines are hard to share. Put the settings in a file called `.side.yml` next to your project; the runner loads it automatically from the current folder (or pass another file with `--config-file`):

```yaml
capabilities:
  browserName: firefox
  "moz:firefoxOptions":
    args: ["-headless"]
baseUrl: "https://the-internet.herokuapp.com"
```

Options on the command line are merged on top of the file. One trap: a `timeout` in `.side.yml` has no effect in 4.1.0-beta.3, because the command line's default of 15000 always wins (we set 3000 in the file and the runner's debug output still showed 15000). Set the element timeout with `-t` instead. A `-c "browserName=chrome"` replaces the browser but keeps the other capabilities from the file, which chapter 7 uses to run the same configuration in several browsers.

## Reports, screenshots and exit codes[#](https://testingbot.com#reports-screenshots-and-exit-codes)

For unattended runs, add a report and screenshots:

```bash
selenium-side-runner -o results -z screenshots the-internet.side
```

We ran this on a project with two tests that fail on purpose. The runner wrote `results/results-2026-11-13T08-15-05.030Z.json` (Jest's JSON format, with each test's title and status: `Running test Fallback demo failed`) and one PNG per failed test in `screenshots/`, named after the test, for example `Verify demo_1794557713386.png`.

The **exit code** is what CI systems look at:

- `0` when every test passed,
- `1` when at least one failed.

Our local runs of the full project exited with 0; the run with the two broken tests exited with 1. Any CI system (GitHub Actions, GitLab CI, Jenkins) can run `selenium-side-runner` as a step and fail the build on a non-zero exit. The CI job then needs Node.js, the runner and a browser, or it sends the browsers to a grid, which is the next chapter.

Your CI step runs `selenium-side-runner the-internet.side || true` so that "the logs are always collected". What is the problem?

 The step now always succeeds, so a failing test never fails the build `|| true` makes the runner skip failed tests Nothing; the runner always exits with 0 anyway

The runner exits with 1 when a test fails, and `|| true` throws that away. Collect reports and screenshots in a step that runs even after a failure (most CI systems have an "always" condition for this) instead of hiding the exit code.

[Previous · Chapter 6 Reusing Tests and Organising Suites in Selenium IDE](https://testingbot.com/resources/courses/selenium-ide/reusing-tests-and-suites) [Next · Chapter 8 Run Selenium IDE Tests on the TestingBot Grid](https://testingbot.com/resources/courses/selenium-ide/run-on-testingbot)

On this page

1. [Install](https://testingbot.com#install)
2. [Run the project](https://testingbot.com#run-the-project)
3. [Capabilities: which browser, how](https://testingbot.com#capabilities-which-browser-how)
4. [Options you will use](https://testingbot.com#options-you-will-use)
5. [A configuration file: .side.yml](https://testingbot.com#a-configuration-file-side-yml)
6. [Reports, screenshots and exit codes](https://testingbot.com#reports-screenshots-and-exit-codes)

Certification

Earn the free, resume-worthy TestingBot Selenium IDE Certification for this course.

[How it works](https://testingbot.com/resources/courses/selenium-ide/certification)
