Selenium IDE: A Guide for Browser Test Automation

Selenium IDE records browser interactions as editable Selenium command-based tests, then replays a selected test or suite. A project stores its base URL, tests, and suites in a single .side file. You can start with in-IDE recording and playback, then use the command-line runner and a Selenium Grid when you need broader browser coverage or remote execution.

There is a version caveat: Selenium’s overview still describes the IDE as a browser extension, while the Selenium IDE v4 materials and current SeleniumHQ repository describe a desktop Electron application. Check the current official installation and release instructions before following setup steps written for an older generation.

1. What Selenium IDE does

Selenium IDE is a record-and-playback authoring tool for browser tests. You perform actions in a browser, such as opening a page, clicking a control, or entering text. The IDE records those actions as Selenium commands. You can inspect and edit the commands, add commands manually, group tests into suites, and replay a test or suite.

It can help a new Selenium user learn the command vocabulary without beginning with a hand-written test framework. Recording is a starting point, though: generated selectors and recorded flows need review, and a recorded test is not automatically a reliable regression test.

IDE playback, runner, and Grid

Execution path	Useful for	What to account for
IDE playback	Authoring and replaying a test or suite during development	Playback uses the IDE’s browser window or opens another window. It is not the same setup as a CI runner.
Command-line runner	Running saved `.side` tests outside the IDE window	Install the runner and configure a browser and its driver for local execution; verify current runtime instructions.
Selenium Grid	Remote browser sessions and broader execution infrastructure	Provide a Grid endpoint and manage the remote environment, browser availability, capacity, and any service costs.

2. Install the right Selenium IDE generation

Official Selenium pages describe different product generations. The overview page describes an extension for Chrome, Firefox, and Edge. SeleniumHQ’s v4 project materials explain the move away from the web-extension model, and the current repository describes an Electron application distributed through release binaries, npm, or a manual build.

Open the official Selenium IDE project and release materials linked below.
Choose the currently supported installation route for your operating system and intended browser workflow.
Check the release or package instructions for runtime requirements and compatibility. Do not assume old Node.js prerequisites or browser examples remain current.
Launch the installed IDE and confirm it can open the application under test before recording a full scenario.

Sources: Selenium IDE overview, Selenium IDE repository and installation options, and Selenium IDE v4 project wiki.

3. Record and save your first test

The exact controls can change between IDE versions, but the project workflow is straightforward: create a project, set its application base URL, record actions, inspect the generated commands, replay, and save.

Create a project. Give it a name that describes the application or test area.
Set the base URL. Use the application’s root URL so tests can navigate with relative paths where appropriate.
Start recording. Let the IDE open the application, then perform a short, deterministic workflow. For a first test, choose a path with a stable starting state and a clear expected result.
Stop and inspect. Review each recorded command and locator. Replace brittle selectors where possible with stable IDs, accessible attributes, or other application-supported hooks.
Add an assertion. A useful test checks an outcome, such as a confirmation element being present, rather than merely replaying clicks.
Replay the test. Run it from a clean or known state and fix any timing or locator problems.
Organize and save. Put related tests into suites and save the project as a .side file.

A project starts with a default suite in the documented workflow. You can add commands manually as well as record interactions. Treat the saved .side file as the portable project artifact to review and version with your test work.

Source: Selenium IDE getting started. Its interface instructions were last updated in 2019, so use it for the concepts and confirm current control names in your installed version.

Make a recorded test maintainable

Keep each test focused on one user outcome.
Prefer selectors tied to stable application behavior over selectors that depend on generated classes or page layout.
Use explicit waits tied to a meaningful state when the application updates asynchronously.
Make test data and starting conditions repeatable. Clean up or reset state when a test changes shared data.
Review the test after UI changes. Recording captures what happened once; it does not prove the locator is stable across releases.
Use suites to group related checks, but keep failures easy to isolate.

4. Run a saved .side project from the command line

The Selenium command-line runner loads saved IDE projects so they can run outside the authoring window. At a high level, install selenium-side-runner, install the browser you intend to use, provide its matching driver or supported driver setup, and point the runner at the .side file. The exact package commands and supported runtime matrix can change; follow the current runner documentation and package metadata rather than copying an old Node.js 8 or 10 prerequisite.

The command-line runner documentation describes browser selection through capabilities, local browser and driver setup, headless Chrome configuration, base URL overrides, suite-level parallelism and worker configuration. It also describes using a Selenium Grid server URL for remote sessions.

# Install the runner using the current official instructions for your environment.
# Then run the saved project with the runner's documented CLI syntax.
selenium-side-runner path/to/project.side

This is an invocation-shape example, not a complete environment-independent install recipe. Confirm the current CLI flags and package requirements in the official command-line runner documentation.

Local browser and driver setup

Choose a browser supported by the current runner and install it on the execution machine.
Install or configure the compatible browser driver as the current Selenium instructions require.
Run one test locally before adding parallel workers. This separates basic browser/driver issues from test concurrency issues.
Configure the runner’s browser capabilities and headless options using current documentation.
If the project uses a base URL override, confirm the test paths resolve against the target environment.

Remote Grid setup

For remote execution, configure the runner to connect to the Grid server URL and request the needed browser capabilities. The Grid must have matching browser capacity and be reachable from the runner. A hosted Grid can reduce local browser maintenance, but introduces provider configuration, network dependencies, concurrency limits, and potentially usage charges. The runner documentation names Sauce Labs as an example of hosted Grid execution; check current provider terms and costs directly before choosing a service.

Parallel runs

The runner documentation describes suite-level parallelism and worker-count configuration. Parallelism can shorten wall-clock time when tests are independent and browser capacity is available. It can also expose shared-state bugs, race conditions, rate limits, or resource contention. First make tests deterministic in serial runs, then increase concurrency gradually and watch for failures that only occur when tests overlap.

Source: Selenium IDE command-line runner. Its page contains older runtime and browser examples; use its execution concepts and verify exact current syntax and supported versions.

5. Exporting and extending beyond .side

The Selenium IDE repository describes a modular project with an Electron IDE, a Node.js side-runner, a shared side-runtime, and exporters for C#, Java, JavaScript, Python, and Ruby. An export can provide a path toward code-based tests or integration with an existing stack, while keeping a .side-centered workflow is useful for teams that prefer the IDE authoring format.

Check the current exporter support and inspect generated code before adopting it. Export does not remove the need to review locators, assertions, test data, waits, and cleanup. The repository identifies selector accuracy as ongoing work, which is a reminder to validate generated selectors against the application rather than treating them as durable by default.

Source: Selenium IDE repository.

6. When Selenium IDE is a good fit

Need	How IDE fits	Trade-off to consider
Learn Selenium commands	Recording exposes command-based tests through browser interactions.	You still need to understand what commands and locators mean to maintain the result.
Quickly draft a browser flow	Record ordinary user actions, then edit and replay them.	Generated selectors and timing assumptions can be fragile.
Keep a human-editable project	Tests and suites can be saved together in a `.side` file.	Teams need to decide whether this format or exported code best fits their review and maintenance process.
Run across browsers or infrastructure	Use the command-line runner with local browsers or a Grid.	Browser, driver, runtime, Grid, and CI configuration add operational work.

If your team needs highly customized fixtures, abstractions, or application-specific test utilities, compare recorded authoring with hand-coded browser automation. The right choice depends on how much authoring speed, code control, selector stability, and infrastructure ownership matter for your tests.

7. Troubleshooting

Symptom	Likely cause	Fix
The IDE is not available as the extension shown in an old tutorial.	The tutorial may describe an older product generation; v4 materials describe a desktop Electron app.	Use the current Selenium IDE repository and release instructions. Confirm the build and install route for your platform.
The runner command is missing.	The runner is not installed, or its executable is not on the shell path.	Follow current package installation instructions, then verify the install location and shell path.
A local run cannot start the browser.	Browser or driver is missing, incompatible, or not discoverable by the runner.	Install a supported browser and configure the matching driver according to current Selenium guidance.
A test fails to find an element.	The locator is brittle, the page changed, or the element has not appeared yet.	Inspect the locator, prefer a stable application selector, and wait for the relevant state before interacting.
A click or typing step runs too early.	Page navigation or asynchronous rendering has not completed.	Wait for a meaningful element or condition instead of relying only on a fixed delay.
The test passes in the IDE but fails in command-line execution.	The environments may differ in browser version, base URL, data, timing, capabilities, or session state.	Compare the environment and capabilities, make setup explicit, and reproduce the command-line run locally.
Parallel execution produces intermittent failures.	Tests may share data or accounts, overload a dependency, or compete for limited browser capacity.	Isolate test state, reduce worker count, and increase parallelism only after serial repeatability is established.
Grid sessions fail to connect or start.	The endpoint is unreachable, requested capabilities are unavailable, or the Grid has no free capacity.	Check connectivity, server URL, requested browser capabilities, and Grid capacity.
Old setup commands or browser names do not work.	Documentation examples can reflect an older runner or browser generation.	Check current runner package metadata and documentation for supported runtime, flags, and browsers.

8. Performance, reliability, and cost

Performance

Browser startup, page load, application response time, and test waits often dominate runtime. Reuse the runner’s supported execution model, keep each test focused, and run only the necessary browser matrix on each change. Parallel workers can reduce elapsed time when the Grid or machine has capacity, but can slow runs or increase flakiness when resources are saturated.

Reliability

Reliability comes from repeatable test data, stable selectors, explicit state-based waits, and controlled browser environments. A successful recording is not evidence that a test will remain valid after a UI change. Rerun tests after changing selectors or setup, and investigate whether intermittent errors come from the application, test state, browser environment, or concurrency.

Cost and operational effort

The IDE project itself does not establish a price for browser infrastructure. Local execution uses machine and maintenance time for browser and driver setup. Remote Grid execution may involve hosted-service charges and capacity planning; compare current provider pricing and terms directly. Include CI compute, test runtime, and maintenance work when evaluating the total cost of a browser-testing approach.

9. Screenshot the result without managing browser automation

For test authoring and interaction checks, Selenium IDE gives you a recorded, editable browser test. For capturing a page image or PDF, ScreenshotNeo is the alternative to try first: it is a website screenshot API and MCP server, and only clean shots are billed.

Or skip the browser setup

Make a GET request to capture a page. See the ScreenshotNeo API documentation for the available options.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets; each step can be turned off.
Bot checks, blank pages, timeouts, and failed loads are not billed. Cache hits also cost nothing, and response headers report the page verdict and billing status.
An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free, and every feature is on every plan.

10. Frequently asked questions

How do I save and run a .side file?

Save the IDE project as a .side file. Replay it in the IDE for authoring, or use the current Selenium side-runner instructions for command-line execution with a configured browser and driver.

Can Selenium IDE run tests in other browsers?

The IDE overview names Chrome, Firefox, and Edge for its extension context. The command-line runner documents browser capabilities and Grid execution. Check current release and runner documentation for the supported browser matrix.

What changed in Selenium IDE v4?

The v4 project materials describe leaving the web-extension model; the current repository describes an Electron application. Older overview pages may describe the extension generation.

Does recording create stable test coverage automatically?

No. Review selectors, add checks for expected outcomes, control test state, and replay after application changes.