Run .side Files with selenium-side-runner
On this page
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#
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.
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#
From the folder that contains the-internet.side:
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#
-c (or --capabilities) passes WebDriver capabilities as key=value pairs separated by spaces. Dots create nested values and square brackets create lists:
# 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#
| 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 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?
--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#
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):
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#
For unattended runs, add a report and screenshots:
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:
-
0when every test passed, -
1when 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 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.