To run Rails system tests with headless Chrome in GitLab CI, configure Rails to use Selenium, then choose whether Chrome runs in the job container or in a separate Selenium service. The right setup depends on your locked Ruby, Rails, and Selenium versions, database, and GitLab runner’s network and executor. In particular, a remote Selenium browser must be able to reach the Rails app; its own localhost is not the job container.
Choose where Chrome runs
There are two common layouts. Neither is universally better; use the one your CI image and runner can support reliably.
| Topology | How it works | What to check |
|---|---|---|
| Chrome in the job container | The Rails test process starts Chrome through Selenium in the same job environment. | The job image must provide the Ruby and browser prerequisites your locked gems require. ChromeDriver management must work for the Selenium version in your lockfile. |
| Remote Selenium service | The job runs Rails tests and connects to a browser in a separate service container using a remote URL. | The service hostname must resolve from the job, and the browser container must be able to reach the Rails app server over the runner’s network. |
Local Chrome is simpler when a suitable job image is available. A remote service can separate browser dependencies from the application image, but adds network configuration and another container whose image and endpoint must be maintained.
Configure Rails system tests
In your system-test base class, select the remote browser only when SELENIUM_REMOTE_URL is set. Otherwise Rails uses local Chrome. This follows the Rails guide’s documented pattern; check the API against the Rails and Selenium versions in your application.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
url = ENV.fetch("SELENIUM_REMOTE_URL", nil)
options = if url
{ browser: :remote, url: url }
else
{ browser: :chrome }
end
driven_by :selenium, using: :headless_chrome, options: optionsFor example, place the configuration in test/application_system_test_case.rb if that is where your application defines its shared system-test setup. If you use a different test directory or base class, put it in the class your system tests actually inherit from.
Build a GitLab CI job around your application
There is no universal Rails CI image or database service. Start with the application’s .ruby-version, Gemfile.lock, database configuration, and runner executor. The following is a job skeleton, not a copy-paste guarantee: replace the image, database service, and environment values with versions and names compatible with your project.
stages:
- test
rails_system_tests:
stage: test
image: ruby:YOUR_RUBY_VERSION
services:
- name: postgres:YOUR_POSTGRES_VERSION
alias: db
variables:
RAILS_ENV: test
DATABASE_URL: "postgresql://postgres:postgres@db:5432/app_test"
before_script:
- bundle install
- bin/rails db:prepare
script:
- bin/rails test:systemThe example assumes a PostgreSQL service reachable as db; it does not install or start Chrome. Add a compatible browser setup to the job image or configure a Selenium service as described below. Your project may need additional packages, credentials, asset compilation, or a different test command. Confirm the command used by your Rails version and repository.
Pin compatible prerequisites
- Use the Ruby version declared by the project and the dependency versions resolved in
Gemfile.lock. - Choose a Chrome and Selenium setup compatible with the locked
selenium-webdrivergem and the runner’s ability to obtain browser or driver packages. - Configure the CI database to match the test database adapter and settings. A service name such as
dbis reachable through the CI network;localhostwould refer to the job container. - Do not assume GitLab’s own build image is a general Rails image. GitLab documents Ruby, Chrome, Node, PostgreSQL, and other tools in its own pipeline image because those serve GitLab’s repository and build. GitLab CI configuration internals.
Connect Rails to a remote Selenium service
Set SELENIUM_REMOTE_URL to the service hostname and port that the job can resolve. For instance, if your CI service is assigned the alias selenium, the URL will generally use that alias, but use the actual endpoint and protocol provided by your selected service image. GitLab’s Selenium Server project illustrates a service alias and endpoint; verify its current image and endpoint before adopting that example as a Rails recipe: GitLab Selenium Server project.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
The remote browser also needs a route back to the app served by Capybara. Rails documents this pattern for containerized remote browsers:
Capybara.server_host = "0.0.0.0"
Capybara.app_host = "http://#{IPSocket.getaddress(Socket.gethostname)}" if ENV["SELENIUM_REMOTE_URL"].present?Binding to 0.0.0.0 lets the app server accept connections on the container’s interfaces; it does not itself make the app reachable. The address advertised by app_host must be routable from the Selenium container in your runner’s network. The Rails guide explicitly notes that a remote app needs extra configuration so Capybara can call it from the remote browser. See Rails system testing with Selenium.
Check both directions of the connection
- The Rails job must resolve and connect to the Selenium service URL.
- The browser container must resolve and connect to the Rails app host and port Capybara advertises.
- Do not substitute
localhostfor a service alias. In a separate container,localhostmeans that container itself, not the job or another service. - Use the hostname or IP appropriate to the runner’s network. The Rails guide’s socket-address example is a pattern, not a guarantee that the resulting address is reachable in every executor setup.
Rails describes the result of correctly configuring the remote browser and server this way: “Now you should get a connection to the remote browser and server, regardless if it is running in a Docker container or CI.”
Do you need to install ChromeDriver separately?
Not necessarily. GitLab documents that Selenium Manager, included with selenium-webdriver, can automatically manage ChromeDriver starting with Selenium 4.6. That is a version-qualified capability, not a reason to remove driver setup without checking your application’s locked gem and runner constraints. If the runner cannot obtain the required driver or browser, automatic management may not solve the environment problem. See GitLab’s frontend testing guide.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Plan runner capacity and test duration
System tests start the application stack and exercise it through a browser, so they are slower and more resource-intensive than tests that do not need a browser. Keep them for behaviors that depend on a real browser, and cover other behavior with lower-level tests where those tests can verify it reliably. GitLab’s guidance on test levels discusses their cost and scope: GitLab testing levels.
GitLab’s CI documentation says jobs using its GLCI_MEDIUM_RUNNER_REQUIRED variable need runners with at least 4 cores and 16 GB of RAM, and notes that Chrome 133 and later increase resource demand for GitLab’s system tests. This is guidance for GitLab’s own workload, not a universal Rails minimum. GitLab also warns that its tests can become unpredictable when the Rails app and PostgreSQL share insufficient resources. Size your own jobs against your workload and runner measurements rather than treating GitLab’s numbers as a requirement for every project. See GitLab CI configuration internals.
Keep JavaScript-driven test data visible and isolated
With a JavaScript-capable browser driver, application and test code may run in separate threads. A test that creates records inside a transaction can leave those records invisible to the app thread. GitLab’s testing guidance notes that such tests may need committed data and cleanup by truncation instead of transaction rollback. Apply that approach only where your test setup requires it, and ensure cleanup still runs when a test fails. See GitLab testing levels.
Troubleshoot common CI failures
Rails cannot connect to the Selenium service
Check the value of SELENIUM_REMOTE_URL, the service alias, port, and protocol against the selected image’s current documentation. Confirm the job and service share a network in the chosen GitLab executor. A typo or use of localhost where a service alias is needed prevents the job from reaching the browser.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
The Selenium browser cannot load the Rails app
The browser is in a different container, so the app host must not resolve to the browser container’s own loopback address. Ensure Capybara binds to an interface reachable from the service and advertises a host and port routable from that container. Check the runner’s actual network topology; an address that works on one executor may not work on another.
Chrome or ChromeDriver fails to start
Verify the browser exists in the environment where local Chrome is expected to run, and check that it is compatible with the locked Selenium setup. If relying on Selenium Manager, confirm selenium-webdriver is version 4.6 or later and that the runner’s network and package constraints allow driver management. Otherwise use an explicitly compatible browser and driver setup for your image.
The browser exits, times out, or the job is unstable under load
Inspect runner CPU and memory pressure, especially when Rails and the database share a constrained runner. Reduce unnecessary concurrency or move the browser/database workload to adequately provisioned runners. GitLab’s Chrome 133+ resource note concerns GitLab’s own tests; it is a prompt to check resource headroom, not a universal sizing formula.
A test cannot see records created by the test thread
For JavaScript-driven tests, check whether transaction-based cleanup isolates data from the app thread. If so, arrange for the test data to be committed and use a cleanup strategy such as truncation that fits your suite’s isolation requirements.
Recommended Free Tools
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Debug headless browser behavior
Headless mode is appropriate for CI jobs without a desktop display. GitLab’s own test configuration documents WEBDRIVER_HEADLESS=false and, on another testing page, WEBDRIVER_HEADLESS=0 for visible-browser debugging. These are GitLab project conventions, not standard Rails environment variables. They will have no effect in another application unless its test configuration reads them. See GitLab frontend testing and GitLab test-running guide.
Or skip the browser setup
For a website screenshot rather than an interactive Rails system test, ScreenshotNeo offers a screenshot API and MCP server. A single request can capture a URL; it is not a replacement for exercising your application’s user flows in system tests. The request below saves a WebP screenshot of the target page. Replace the URL with one your API request is authorized to access. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie/consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
- Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents and other MCP clients. - The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Where should I put the Selenium configuration in Rails?
Put it in the shared system-test base class used by your tests, commonly test/application_system_test_case.rb; adapt the location to your application’s test structure.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Are WEBDRIVER_HEADLESS variables standard Rails settings?
No. The cited variables are conventions documented for GitLab’s own testing setup. Another app must explicitly read them for them to affect its tests.
Quick Recap
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.
