Cross-Browser Testing with Watir: A Practical Guide

Cross-browser testing with Watir means running the same user-focused scenarios in explicitly selected browser sessions, then checking that each browser supports the behavior your product needs. Watir provides the Ruby interface; Selenium WebDriver controls the browser through a browser-specific driver. Choose a browser matrix that matches your product, configure a valid local or remote session for each target, and keep browser-specific setup separate from reusable test intent.

Watir documents selecting a browser when creating a session, including Chrome, Firefox, Edge, Safari, and Internet Explorer. Treat that list as documented behavior, not a promise that every current Watir, Selenium, browser, and operating-system combination is supported. The Watir session guide was last updated in 2021, so confirm the syntax and setup against the versions you use. Watir: Starting a Session

1. Choose a browser matrix that reflects your product

There is no universal browser matrix. Select targets from your product requirements, supported operating systems, and the browser-specific behavior your application depends on. Selenium’s supported-browser documentation notes that each browser has custom capabilities and unique features. Selenium: Supported Browsers

Decision	What to establish
Browser targets	Which browsers your product supports and which browser-specific behaviors matter to users.
Operating systems	Where each browser session must run. Some browser and setup choices depend on the operating system.
Execution location	Whether tests run on the machine running Ruby or on a remote WebDriver host.
Special capabilities	Whether a scenario needs a profile, preferences, permissions, or another browser-specific option.
Legacy coverage	Whether an older browser is required by the product. Its appearance in documentation alone is not a reason to add it to a new project.

Keep the scenario focused on product behavior. For example, test that a user can submit a form and sees a confirmation; avoid making the test depend on incidental layout details unless layout itself is the requirement.

2. Set up the Ruby project and local browser sessions

A local run needs Ruby dependencies, an installed browser, and a compatible WebDriver driver available where the session starts. Selenium WebDriver is the browser-control layer: its driver communicates with the browser and relays commands. Selenium: Installation and WebDriver

Install Watir in your project using Bundler:

# Gemfile
gem "watir"

bundle install

Current driver-management behavior can vary with your Watir and Selenium versions. Watir’s driver guide historically recommended the webdrivers gem for automatic downloads, but that guide is dated. Check current Watir and Selenium installation documentation before adding a driver-management gem or relying on automatic downloads. Watir: Drivers · Selenium: Browser Drivers

Here is a small runnable example for a local browser session. Set BROWSER to a browser symbol supported by your installed Watir/Selenium versions. Ensure that browser and its compatible driver are installed in the environment running the script.

# cross_browser.rb
require "watir"

browser_name = ENV.fetch("BROWSER", "chrome").to_sym
browser = Watir::Browser.new(browser_name)

begin
  browser.goto("https://example.com")
  heading = browser.h1
  abort "Expected the example heading" unless heading.exists?
  puts "#{browser_name}: #{heading.text}"
ensure
  browser.close
end

# Examples
BROWSER=chrome bundle exec ruby cross_browser.rb
BROWSER=firefox bundle exec ruby cross_browser.rb
BROWSER=edge bundle exec ruby cross_browser.rb

The Watir session guide shows Watir::Browser.new for the default browser and forms such as Watir::Browser.new :firefox to select a browser. The code above uses the same selection idea while allowing the target to be supplied through an environment variable. Confirm browser symbols and options against the Watir version in your bundle.

3. Reuse scenarios while selecting sessions explicitly

Put the target list in one place and keep test steps reusable. The example below uses Minitest, which ships with Ruby, and opens a fresh browser for each target. It is a compact pattern to adapt; it does not imply that any browser/version combination has been tested here.

# test_cross_browser.rb
require "minitest/autorun"
require "watir"

BROWSERS = ENV.fetch("BROWSERS", "chrome,firefox")
                  .split(",")
                  .map { |name| name.strip.to_sym }
                  .freeze

class CrossBrowserTest < Minitest::Test
  def test_homepage_has_expected_heading
    BROWSERS.each do |browser_name|
      browser = Watir::Browser.new(browser_name)
      begin
        browser.goto("https://example.com")
        assert browser.h1.exists?, "#{browser_name}: expected an h1"
        assert_equal "Example Domain", browser.h1.text,
                     "#{browser_name}: unexpected heading"
      ensure
        browser.close
      end
    end
  end
end

BROWSERS=chrome,firefox bundle exec ruby test_cross_browser.rb

For a larger suite, use your test framework’s setup and teardown hooks to create and close one session per test or per worker, according to isolation needs. Avoid sharing a browser session between parallel workers. Keep assertions about user-visible outcomes common across browsers; place genuinely browser-specific setup in a small configuration layer.

4. Configure browser-specific behavior only when needed

Browser selection is only one part of session configuration. Browser-specific options can include capabilities, profiles, preferences, and permissions. Watir’s browser guides cover Chrome, Firefox, Edge, and Safari settings; those pages are historical and should be checked against current library and browser releases before copying specialized options. Chrome · Firefox · Edge · Safari

Profiles and preferences: use them for a real product requirement, such as a configured browser state. Prefer a fresh profile when isolation matters.
Capabilities: configure browser-specific behavior at session creation and keep it out of shared scenario steps where possible.
Safari setup: consult the current Safari and Watir guidance for the required authorization and environment setup before starting sessions.
Internet Explorer: include it only where a product or legacy support requirement calls for it, and verify whether the intended environment supports the complete setup.

Avoid assuming that a Chrome run represents Firefox, Safari, or Edge. Cross-browser coverage is useful precisely because browser capabilities and behavior can differ.

5. Run browsers remotely when the environment calls for it

Watir documents connecting to a browser on another machine by supplying a remote WebDriver URL. The Ruby test still selects and controls a browser session, while the remote environment supplies the browser and driver. Remote execution moves provisioning and session management to that environment; it does not remove the need to configure a valid browser session. Watir remote sessions

A minimal remote-session shape is:

require "watir"

remote_url = ENV.fetch("SELENIUM_REMOTE_URL")
browser = Watir::Browser.new(
  :chrome,
  url: remote_url
)

begin
  browser.goto("https://example.com")
  puts browser.title
ensure
  browser.close
end

Check the current Watir session documentation for the exact remote options accepted by your version and configure the remote endpoint to accept the requested browser. Do not put endpoint credentials in source control. Watir’s driver guide names hosted browser services such as BrowserStack and Sauce Labs, but the available research does not establish their current integrations, coverage, or pricing; verify those details with the provider before choosing one.

6. Organize a reliable cross-browser workflow

Define supported targets. Record browser, operating system, and any required browser-specific behavior.
Validate session creation first. Run a small navigation smoke test for each target before debugging application assertions.
Run the same scenarios per target. Parameterize browser selection and report the browser name with each failure.
Isolate sessions. Close each browser in an ensure/finally path and avoid sharing mutable profiles or sessions across parallel work.
Keep evidence useful. On failure, record the selected browser, relevant versions, and whether the run was local or remote. Avoid logging secrets or sensitive page data.
Recheck compatibility after upgrades. Browser, driver, Selenium, and Watir changes can affect session startup or behavior; verify their compatibility in the execution environment.

7. Troubleshoot common failures

Symptom	Likely layer	Checks and fixes
Session creation says the browser is unknown or unavailable	Watir selection or environment	Check the browser symbol and the Watir/Selenium version. Confirm that the selected browser is installed where the session actually runs.
Driver executable cannot be found	Driver installation or PATH	Install or configure the compatible driver for that browser, and verify its location in the local or remote execution environment. Selenium’s driver guide explains the driver’s role in sending commands to a browser. Driver troubleshooting
Driver/browser compatibility or session handshake error	Version compatibility	Check the browser, driver, Selenium, and Watir versions together. Update or pin compatible components according to their current documentation; do not assume an old automatic-download recipe still applies.
Remote connection refused or times out	Remote endpoint or network	Check the endpoint URL, reachability from the test runner, remote service availability, and whether the endpoint accepts the requested browser and capabilities.
Browser opens but the test cannot find an element	Page timing or application behavior	Check that navigation reached the expected page, then wait for the relevant condition using Watir’s element waiting methods rather than adding arbitrary long sleeps. Confirm the locator still matches the page in that browser.
Safari session fails before navigation	Browser-specific authorization/setup	Review current Safari and Watir setup instructions for the machine and user running the test, including required browser authorization.
Only one browser fails a shared assertion	Browser-specific page behavior or test assumption	Inspect the rendered state and application behavior in that target. Separate an actual product difference from a brittle locator, timing assumption, or unsupported capability.
Tests pass alone but fail in parallel	Shared state or resource contention	Give workers isolated sessions and profiles, avoid shared mutable test data, and limit concurrency to what the local or remote environment can support.

8. Performance, reliability, and cost considerations

Running scenarios across more targets increases the number of browser sessions and total execution work. The research dossier provides no benchmark for Watir suite speed or quantified cost comparison, so estimate from your own scenario count, target matrix, and execution environment. Keep a small browser-startup smoke suite for quick diagnosis and run broader coverage at the cadence your delivery process requires.

Local execution gives the team direct control over browser installation and driver diagnostics, while requiring the team to maintain that environment. Remote execution can centralize browser provisioning, while making endpoint availability, queueing, and session configuration part of the workflow. In either case, report failures with enough environment detail to distinguish a browser startup problem from an application regression.

Or skip the browser setup

If your task is to capture a page image or PDF rather than interactively exercise browser behavior, ScreenshotNeo offers a one-request website screenshot API and an MCP server for AI agents. It is a useful alternative to try first when the desired output is a page capture: consent banners are accepted and more than 60 known consent platforms, newsletter popups, and chat widgets can be removed before the shot, with each step configurable. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. AI agents can use its MCP tools to take screenshots. See the ScreenshotNeo API documentation.

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

import requests

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

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await (await import('node:fs/promises')).writeFile('shot.webp', image);

ScreenshotNeo has 1,000 free screenshots per month with no card required; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.

Frequently asked questions

Is there a specific way to handle code for trying multiple browsers?

Yes. Keep the scenario reusable and provide the browser choice through configuration, such as an environment variable or a target list. Create and close a separate session for each target.

Does Watir make browser sessions identical?

No. It provides a consistent Ruby interface, while browser capabilities and behavior can differ. Configure target-specific needs explicitly and verify the product behavior in each required browser.

Should I choose local or remote execution?

Choose based on where you need browsers to run and who should provision and maintain them. Local sessions use the test machine’s browser and driver; remote sessions use a configured WebDriver endpoint.

Can a screenshot replace a cross-browser test?

No. A screenshot is a visual capture. It does not verify interactive behavior such as form submission, navigation, or application state transitions that Watir scenarios can exercise.

Sources and version notes

Several Watir pages referenced here were last updated in 2021. Check current Watir, Selenium, browser, driver, and operating-system documentation before relying on version-specific setup or options.