The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If a Rails system test opens a browser in a separate Docker container, localhost in that browser points to the browser container—not the Rails container. Put the browser and Rails service on a shared Docker network, make Capybara’s test server listen on 0.0.0.0, and set Capybara.app_host to the Rails service name and the test server’s container port. The Selenium URL and the Rails app URL are separate addresses; changing one does not fix the other.
First identify which connection is failing
“Connection refused” and ERR_CONNECTION_REFUSED describe a connection attempt that did not reach a listening service at the requested host and port. In a Dockerized system test, several processes and addresses are involved:
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
DEVELOP WITH C# & ASP.NET CORE: Build Secure APIs and Professional Web Integrations (C# EXTREME USA... | $5.99 | Buy on Amazon |
- RSpec / test runner: runs the test and starts or configures Capybara’s Rails test server.
- Rails test server: serves the app on a port chosen by the test setup.
- Browser: visits the app URL, often from a Selenium container.
- Selenium endpoint: the address the test runner uses to tell the remote browser what to do.
Draw the route that matters: the browser must be able to reach the Rails test server. A Selenium remote URL identifies the browser service; Capybara.app_host identifies the app URL the browser visits. They are not interchangeable.
Before editing configuration, record where each process runs, which network each container joins, the actual Rails test-server port, and the hostname in the failing browser URL. The right host depends on that topology.
#1 Best Overall
Choose the hostname for the Docker topology
Rails and browser are Compose services on a shared network
Use the Rails service name and the port inside its container. If the service is called web and Capybara’s server listens on your actual PORT, the browser-facing pattern is http://web:PORT. Replace both values; PORT is an explanatory placeholder, not a recommended fixed port.
Compose services on the same network can resolve one another by service name. For this internal route, use the container port, not the published host port. A mapping such as HOST_PORT:CONTAINER_PORT is for access from outside the container network; it does not mean another service should use HOST_PORT. Service names are also safer than container IPs, which can change when containers are recreated.
Rails runs on the host and the browser is in a Linux container
This is a different route: the browser container needs a way to reach the host machine. Docker documents mapping host.docker.internal to host-gateway on Linux. The Rails server must also listen on an interface reachable from that container. Do not substitute this host-gateway route for Compose service DNS when Rails is already a service reachable on the shared network.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →The browser and Rails have no shared or routed network
A published port alone does not establish that a browser container can reach Rails. Check the browser’s network location and create a deliberate route: commonly, attach the relevant Compose services to a shared network, or use the appropriate host route if Rails truly runs on the host. Avoid guessing from the test runner’s perspective; the browser itself must be able to resolve and connect to the target.
Bind Capybara’s server beyond loopback
A correct app_host cannot help if the Rails test server only listens on the container’s loopback interface. Rails’ remote system-test example sets Capybara.server_host = "0.0.0.0", allowing connections through the container’s network interfaces. This binding does not choose a hostname for the browser: configure app_host separately with an address reachable from that browser.
For a Compose service named web, the core settings have this shape:
Capybara.server_host = "0.0.0.0"
Capybara.app_host = "http://web:PORT"This is a topology-dependent sketch, not a complete project configuration. Use the actual service name, scheme, and port that the Rails test server listens on. Keep any remote Selenium driver setting pointed at the Selenium service, not at web.
Put settings where RSpec actually loads them
Do not assume that editing Rails’ ApplicationSystemTestCase configures an RSpec system spec. RSpec Rails documents that its system specs wrap Rails system tests but do not use the ApplicationSystemTestCase helper configuration. If changes there have no effect, move equivalent settings to the RSpec system-spec setup path your project loads—for example, the relevant support/configuration file required by your RSpec setup.
Check that the settings execute for system specs, not just ordinary model or request specs. Also check for later configuration that overwrites app_host or the server host. Rails’ remote browser example uses SELENIUM_REMOTE_URL to select a remote Selenium driver and sets app_host to the address the remote browser can reach; adapt that pattern to your network and installed versions.
Verify the route from the browser’s side
- Inspect Compose network membership. Confirm that the Rails service and browser service are attached to a common network, or that a deliberate alternate route exists. Compose’s default project network normally connects services in the same project.
- Confirm the service name and port. Use the Rails service name from the Compose configuration and determine the actual port used by Capybara’s test server. Do not infer it from a published host mapping.
- Inspect published mappings if relevant. Run
docker compose port SERVICE CONTAINER_PORTfor a service and port you have identified. This reports a host-published mapping; it is useful for host access, but does not replace the service-name/container-port route between same-network containers. - Test from a running container. From the browser container, try reaching the intended app URL using a connectivity tool available in that image. Check name resolution and whether a connection to the expected port succeeds. Testing only from the Rails or test-runner container can miss the browser’s separate network perspective.
- Check the listener. Confirm the test server started, is listening on the expected port, and is bound to
0.0.0.0when remote access is needed. A process bound only to loopback is not reachable through the container interface. - Retry after recreating changed services. If you have hard-coded an IP, replace it with service DNS. Container addresses may change after recreation; a stable Compose service name avoids maintaining an IP manually.
Common causes and targeted fixes
| Symptom or setup | Likely cause | What to change or verify |
|---|---|---|
Browser URL uses localhost or 127.0.0.1; browser is in another container |
Loopback refers to the browser container itself. | Use the Rails service name and container port on a shared Compose network. |
| Service name is correct, but connection is refused | The server may not be running, may use another port, or may listen only on loopback. | Confirm the test-server port and bind Capybara to 0.0.0.0. |
| URL uses the published host-side port for service-to-service traffic | The host mapping is being confused with the container port. | Use the container port for same-network Compose traffic; reserve the published mapping for access through the host. |
| Configuration changes have no effect on RSpec system specs | Settings were placed only in ApplicationSystemTestCase or a file RSpec does not load. |
Put them in the system-spec configuration path RSpec actually loads and check for overrides. |
| Works until a container is recreated | A container IP was hard-coded. | Use Compose service-name DNS rather than a fixed container IP. |
| App URL and Selenium URL appear to be the same | The browser endpoint and the Rails destination have been conflated. | Point the remote driver at Selenium; point app_host at Rails from the browser’s network. |
Or skip the browser setup
ScreenshotNeo is a website screenshot API, not a replacement for a Rails system test: it will not run RSpec, exercise your app’s test suite, or repair Docker networking. If the task is only to capture a page as an image or PDF, its API can avoid configuring a browser container. For a system-test connection failure, continue using the network checks above.
One-call cURL example, using the documented API pattern:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and options. ScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo, then sign up for the free plan.
Cost and reliability considerations for the test setup
For system tests, first distinguish a bad route from a slow or failed app startup. A fast connection refusal usually points to a wrong host, port, network, or listener rather than an assertion failure. If the server starts later than the browser navigation, inspect test-server startup and readiness behavior; increasing a timeout without fixing an unreachable address only delays the same failure.
Prefer service DNS and a shared network over maintaining container IPs. Keep host-published ports for the cases that need host access, and avoid exposing extra ports merely to make two services in the same Compose project communicate. For reproducibility, keep the selected app host, server binding, and remote Selenium endpoint explicit in the RSpec setup that runs in the test environment.
Frequently asked questions
Does changing Capybara.app_host change where Selenium runs?
No. It sets the application address the browser visits. Remote driver configuration identifies the Selenium service that accepts browser commands.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallShould I use 0.0.0.0 as the browser URL?
No. It is the server bind address used to listen on interfaces. Set app_host to a concrete hostname and port that the browser can route to, such as the Rails Compose service name and its container port.
Which Rails and RSpec versions does this apply to?
The cited Rails guide was current when accessed on September 29, 2026, and the RSpec Rails system-spec documentation cited is version 6.0. Check your installed versions if the configuration behavior differs; exact driver options and setup paths depend on the project.
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.
