October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsSlow PC?RecommendedPC slow today? Run a repair scan before it gets worseResolve common Windows issues and optimize system performance.Scan NowOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
Cupertino desk6 min

How to Run Capybara Tests with Selenium and Chrome in a Dockerized Rails Environment on a Mac

Run Rails browser tests with Capybara and remote Selenium Chrome in Docker Compose, while keeping the test-to-WebDriver and browser-to-app network paths straight.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Run Rails tests and Selenium/Chrome in separate Docker Compose services: configure the test process to reach WebDriver at http://selenium:4444, and configure Chrome to reach the Rails test server by its Compose service name and port. Those are two different network connections; using localhost for either one often points at the wrong container.

Use Capybara’s rack_test driver for fast tests that do not need JavaScript, and Selenium Chrome for tests that exercise browser behavior. The example below shows the container topology and a version-dependent Capybara configuration pattern. Match the driver setup to your installed Rails, Capybara, and selenium-webdriver versions; there is no universal compatible version set.

As an Amazon Associate I earn from qualifying purchases.

Choose the right Capybara driver

Capybara’s default rack_test driver is quick, but it does not run JavaScript. Use Selenium with Chrome for tests that need JavaScript or browser behavior. You can keep ordinary tests on rack_test and select a JavaScript-capable driver only for tests that need it, rather than paying the startup and browser cost for every test. Capybara documents the named :selenium_chrome and :selenium_chrome_headless drivers in its driver documentation.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How the Docker network should work

There are two separate connections to configure:

  1. Test process to Selenium: the Rails test process connects to the WebDriver endpoint on the Selenium service, typically http://selenium:4444 when the Compose service is named selenium.
  2. Chrome to Rails: Chrome runs inside the Selenium container and must navigate to the Rails test server using the Rails service hostname and test port, such as http://rails:3000 when the Rails service is named rails.

Within a container, localhost means that same container. It does not automatically mean the Mac host or another service. Compose services on the same network can address one another by service name. The browser itself must be able to reach the app under test, not just the test process.

#1 Best Overall
Apple 2026 MacBook Neo 13-inch Laptop with A18 Pro chip: Built for AI and Apple Intelligence, Liquid Retina Display, 8GB Unified Memory, 256GB SSD Storage, 1080p FaceTime HD Camera; Blush
  • AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
  • FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
  • FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
  • UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
  • A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.

Compose configuration for Rails and Selenium

The official Selenium standalone Chrome image provides a remote WebDriver endpoint on port 4444. The following Compose fragment illustrates the network and shared-memory configuration. Replace the image tag with a version you have checked for your project and platform; image tags and architecture support change, and the available evidence does not establish a universal current pin.

services:
  rails:
    build: .
    command: bundle exec rspec
    environment:
      SELENIUM_URL: http://selenium:4444
      APP_HOST: http://rails:3000
    depends_on:
      - selenium
    # Both services use the default Compose network.

  selenium:
    image: selenium/standalone-chrome:REPLACE_WITH_VERIFIED_TAG
    shm_size: 2gb
    ports:
      - "4444:4444"
      # Optional: expose 7900 only if you need browser inspection via noVNC.

For browser containers, Selenium recommends 2 GB of shared memory; the Compose setting above corresponds to the documented Docker --shm-size=2g guidance. Publishing port 4444 is useful if a client on the Mac host also needs to connect. A test process inside the Compose network should use the service hostname and port, not the host-published port through localhost.

Rank #2
Sale
Apple 2026 MacBook Air 13-inch Laptop with M5 chip: Built for AI, 13.6-inch Liquid Retina Display, 16GB Unified Memory, 512GB SSD, 12MP Center Stage Camera, Touch ID, Wi-Fi 7; Midnight
  • BUILT FOR COLLEGE. AND BEYOND — MacBook Air with the M5 chip packs blazing speed and powerful AI capabilities into an incredibly portable design. And with up to 18 hours of battery life,* this thin and light powerhouse is ready to take on almost any major, just about anywhere.
  • TEAR THROUGH TOUGH ASSIGNMENTS — With its faster CPU and unified memory, the M5 chip delivers even more performance and fluidity across apps, making multitasking and creative workflows smooth and responsive. A powerful Neural Engine and next-generation GPU with Neural Accelerators give you a powerful platform for AI.
  • MAKE QUICK WORK OF YOUR TO-DO LIST — Apple Intelligence helps you write, express yourself, and get things done effortlessly — whether it’s for school or everyday life. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
  • UP TO 18 HOURS OF BATTERY LIFE — MacBook Air delivers incredible battery life with amazing performance, so you can power through a full day of classes without worrying about plugging in.
  • A BRILLIANT 13.6-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Air supports 1 billion colors, making photos and videos pop with rich contrast and sharp detail, and text appears supercrisp. So everything — from class presentations to movies to games — looks truly stunning.

depends_on starts the Selenium service before the Rails service, but it is not a guarantee that WebDriver is ready to accept connections. If your test command begins immediately, add an appropriate readiness check or retry behavior for your project rather than assuming container startup order means service readiness.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Configure Capybara for the remote browser

The exact registration differs between Rails system tests and standalone RSpec/Capybara setups, and depends on installed versions. The key values are the remote WebDriver URL and the application URL Chrome will visit. This RSpec-style sketch shows where they belong; adapt the driver registration to the APIs supported by your dependencies.

Rank #3
Apple 2026 MacBook Neo 13-inch Laptop with A18 Pro chip: Built for AI and Apple Intelligence, Liquid Retina Display, 8GB Unified Memory, 256GB SSD Storage, 1080p FaceTime HD Camera; Indigo
  • AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
  • FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
  • FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
  • UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
  • A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.
# spec/support/selenium.rb
require "capybara/rspec"
require "selenium-webdriver"

Capybara.server_host = "0.0.0.0"
Capybara.app_host = ENV.fetch("APP_HOST", "http://rails:3000")

Capybara.register_driver :remote_chrome do |app|
  options = Selenium::WebDriver::Chrome::Options.new
  options.add_argument("--headless=new")
  options.add_argument("--no-sandbox")
  options.add_argument("--disable-dev-shm-usage")

  Capybara::Selenium::Driver.new(
    app,
    browser: :remote,
    url: ENV.fetch("SELENIUM_URL", "http://selenium:4444"),
    options: options
  )
end

RSpec.configure do |config|
  config.before(:each, js: true) do
    driven_by :remote_chrome
  end
end

This is an illustrative registration, not a tested drop-in recipe for every Rails/Capybara combination. In particular, Rails system tests may configure their driver through Rails’ system-test interfaces rather than an RSpec hook. Follow the documentation for the versions in your lockfile, and verify that the test framework actually selects the remote driver for the tests that need it.

The server must bind to an interface reachable from the browser container. For a standalone test server, that commonly means binding to 0.0.0.0; setting Capybara’s server host alone may not override a separate Rails server command or framework-specific binding option. Ensure the chosen port is reachable on the Compose network.

Rank #4
Apple 2026 MacBook Neo 13-inch Laptop with A18 Pro chip: Built for AI and Apple Intelligence, Liquid Retina Display, 8GB Unified Memory, 256GB SSD Storage, 1080p FaceTime HD Camera; Citrus
  • AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
  • FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
  • FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
  • UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
  • A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.

Run and verify the test setup

  1. Check that your Rails image includes the project’s bundle and test dependencies, including Capybara and selenium-webdriver.
  2. Start the services with docker compose up or run the test command with docker compose run --rm rails, according to your Compose workflow.
  3. Confirm the Selenium container is running and WebDriver is reachable at http://selenium:4444 from the Rails test container.
  4. Run one browser-dependent test. Confirm its browser URL uses the Rails service hostname rather than localhost.
  5. Run non-JavaScript tests with the faster driver where appropriate, and run browser tests with the remote Chrome driver.

From the Mac host, the Selenium image documentation uses http://localhost:4444 as the endpoint when port 4444 is published. That host-side address is not interchangeable with the Compose service address used by a container.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Mac and Apple Silicon considerations

Docker Desktop on Apple Silicon does not guarantee that every Selenium image tag has a native ARM build. Selenium’s Docker repository notes that standard browser images may require Linux/amd64 emulation on Apple M-series systems and points to community-maintained experimental M-series images. Check the architecture metadata and current project status for the exact tag you intend to use; an experimental community image is not a blanket compatibility guarantee. See the Selenium Docker repository.

Best Value
Sale
Apple 2026 MacBook Pro Laptop with Apple M5 Pro chip with 18-core CPU and 20-core GPU: Built for AI, 16.2-inch Liquid Retina XDR Display, 24GB Unified Memory, 1TB SSD, Wi-Fi 7; Space Black
  • FAST RUNS IN THE FAMILY — The 16-inch MacBook Pro with the M5 Pro or M5 Max chip brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. With all-day battery life, double the starting storage,* and a breathtaking Liquid Retina XDR display, it’s pro in every way.*
  • BUCKLE UP — Along with a next-generation CPU, faster unified memory, and up to 2x faster SSD storage,* M5 Pro and M5 Max feature a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance and on-device training capabilities. So you can blaze through demanding workloads at mind-bending speeds.
  • BUILT FOR AI — Apple silicon, and every major component that powers it, is designed to run demanding on-device AI workloads like LLM inference and training. And Apple Intelligence helps you write, express yourself, and get things done effortlessly with groundbreaking privacy protections at every step.*
  • ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.*
  • MACOS RUNS APPS FAST — All your go-to apps run lightning fast in macOS, including built-in apps like FaceTime and Messages. Plus, built-in virus protection and free software updates help keep your Mac running smoothly and securely.

If you use emulation, account for the possibility of different startup time and resource use; do not assume performance is equivalent to a native image without measuring your own test suite. Older Mac-specific Rails examples can illustrate the multi-container topology, but their historical image tags should not be treated as current defaults.

Pin the versions that need to work together

For reproducible CI and local runs, select compatible versions of Ruby/Rails, Capybara, selenium-webdriver, the Selenium image, and the Chrome version bundled with that image. Pin the image tag instead of relying on a floating latest tag. No single version matrix is established for all projects, so validate the chosen combination against your application’s dependency lockfile and current Selenium image documentation.

Common failures and fixes

  • WebDriver connection refused: confirm Selenium is running and ready, port 4444 is listening, both services share a Compose network, and the test process uses selenium rather than its own localhost.
  • Chrome opens but cannot load the Rails page: check that the Rails server binds to a container-reachable interface, the app host is the Rails service name, and the application port is reachable from the Selenium container.
  • Browser crashes or becomes unstable under load: verify the Selenium service has the recommended 2 GB shared memory allocation.
  • Image does not start or is unexpectedly slow on Apple Silicon: inspect the selected tag’s supported architecture and determine whether it runs natively, through emulation, or via an experimental ARM image.
  • Tests break after an image update: pin the prior known-compatible image while checking the updated Selenium/Chrome image against your client dependencies; validate the project-specific version matrix before changing the pin.
  • Tests unexpectedly use a non-browser driver: inspect the framework-specific system-test or RSpec configuration and confirm the test metadata or setup hook selects the Selenium driver for the intended cases.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server, not a replacement for Capybara integration tests. If your goal is to capture a URL rather than verify application interactions, one GET request returns an image or PDF. The service accepts and removes supported cookie/consent banners, newsletter popups, and chat widgets before capture; failed loads, bot checks, blank pages, and cache hits are not billed, with verdict and billing information in response headers. Its MCP server provides screenshot tools for AI agents.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For API parameters, see the ScreenshotNeo documentation. Example cURL call:

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

The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free ScreenshotNeo access.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
Windows Errors? Fix Them Before They SpreadFree repair scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.