To run Selenium tests through CircleCI, configure a job in .circleci/config.yml, start or reach a private Selenium Grid, wait until it is ready, and point your tests’ remote WebDriver client at the Grid endpoint. For a small, disposable run, use a Standalone Grid service in the job’s network; for multiple machines or browser environments, connect to a separately managed Grid. The correct endpoint depends on that network topology—localhost works only when the test process and Grid share the relevant network namespace.
Choose where Selenium Grid will run
CircleCI orchestrates jobs from repository configuration, and the job’s executor determines where its steps run. Selenium Grid receives WebDriver commands and routes them to browser sessions, allowing tests to run against different browsers and in parallel. Choose the topology before writing the endpoint or YAML; neither the endpoint nor container networking is universal. CircleCI pipelines · Selenium Grid
Disposable Standalone Grid for a small run
Run one Grid Standalone service alongside the test job when the test run needs a simple, disposable setup. Standalone defaults to port 4444. In a CircleCI Docker-executor job with a secondary service container on the shared network, the test process should use the service’s configured hostname and port—not automatically localhost. Selenium Grid Getting Started
Separate or shared Grid for broader coverage
Use Hub-and-Node or Distributed Grid when tests need multiple machines, browser versions, operating systems, or more capacity. The client should send commands to the Hub or, in a fully Distributed setup, the Router—not an arbitrary node. Nodes must reach the Grid components they depend on. Selenium documents default Event Bus ports 4442 and 4443 for Hub-and-Node communication; permit only the ports required by your chosen topology. Grid endpoints · Grid setup
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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
Configure the CircleCI job
Put the project configuration at .circleci/config.yml, choose a pinned primary image that contains the test runtime and required dependencies, then add Grid startup or connection, readiness, test execution, and result collection steps. In the Docker executor, the first image is the primary container where job steps run; secondary containers can provide services on the job network. Do not assume that Docker Compose or Remote Docker has the same networking and volume behavior as ordinary secondary containers. CircleCI recommends the machine executor when Compose must manage a multi-container setup. Docker executor · Docker Compose
Topology-aware configuration template
This is a structural template, not a drop-in configuration: select a real pinned image, service image, readiness check, test command, report directory, and Grid hostname that match your project. The Grid service line is intentionally a placeholder rather than an unverified image tag.
Rank #2
version: 2.1
jobs:
browser-tests:
docker:
- image: cimg/<runtime>:<pinned-tag>
# If Grid is a secondary container, add a compatible Selenium
# Grid service image here and use its reachable service hostname.
steps:
- checkout
- run: <install project dependencies>
- run:
name: Wait for Grid readiness
command: <poll the Grid status endpoint with a finite timeout>
- run:
name: Run browser tests
command: <invoke the project test command>
- store_test_results:
path: <test-results-directory>
workflows:
browser-tests:
jobs:
- browser-testsConfigure workflows for the branches or changes that should trigger the job. Use the project’s actual test framework output path for store_test_results; CircleCI does not prescribe one universal report directory. Pipelines · Automated testing · Configuration reference
Point RemoteWebDriver at the reachable Grid URL
In Java, Selenium’s remote client accepts the Grid URL and browser options. Substitute the hostname reachable from the test container, and select capabilities supported by the Grid’s available browser nodes.
URL gridUrl = URI.create(System.getenv("SELENIUM_GRID_URL")).toURL();
ChromeOptions options = new ChromeOptions();
WebDriver driver = new RemoteWebDriver(gridUrl, options);
try {
driver.get("https://example.com");
// Run assertions here.
} finally {
driver.quit();
}Set SELENIUM_GRID_URL to the URL for your topology: Standalone commonly uses http://<reachable-host>:4444; Hub-and-Node clients use the Hub address; Distributed Grid clients use the Router address. Use http://localhost:4444 only if Grid and the test process share the relevant network namespace or CircleCI network arrangement. Check the Selenium binding’s remote-driver API for your language; the endpoint principle is the same. Grid endpoints · CircleCI Docker networking
Make startup, test results, and cleanup reliable
- Start or connect to Grid. Start the disposable service before the test command, or make the private shared Grid endpoint available to the job.
- Wait for readiness with a deadline. Poll the Grid status endpoint using a finite timeout and fail with a useful log if it never becomes ready. A fixed short sleep can pass or fail depending on startup timing; choose a polling command suitable for the job image rather than assuming one universal utility.
- Run the suite and release sessions. Ensure test teardown calls
quit()so sessions return slots to the Grid, including when assertions fail. - Collect reports and diagnostic output. Write framework or JUnit-style reports to the configured path and use CircleCI test-result storage. Keep enough job and Selenium server logs to distinguish test failures from Grid startup, routing, and browser failures.
CircleCI documents background Selenium startup and test-result integration, but a particular readiness command or report path must be chosen for the project. Avoid copying the older Selenium server download example in CircleCI’s browser-testing page as a current version recommendation; use Selenium’s current Grid setup guidance for present-day commands. CircleCI browser testing · Test output · Selenium Grid setup
Plan parallelism around measured capacity
Grid can distribute sessions, but more parallel tests do not guarantee a faster pipeline. Runtime depends on test duration, queueing, available Grid slots, CPU and memory limits, browser startup, and stability under load. Selenium’s current Getting Started guidance suggests approximately 1 GB of RAM per browser session and a default maximum concurrent-session limit tied to available processors. These are operational recommendations, not guarantees or a benchmark for your workload; measure your own sessions before raising concurrency. Selenium sizing guidance
| Choice | Operational trade-off | Best fit |
|---|---|---|
| Standalone | One service to start and diagnose; browser availability and capacity are limited to that environment. | Small, disposable runs and straightforward setup. |
| Hub-and-Node or Distributed | More components and network paths to operate; can bring together separate nodes and browser environments. | Broader browser or platform coverage and capacity beyond one machine. |
Increase parallelism only when the Grid has free slots and the CI job and browser nodes have measured CPU and memory headroom. Check Selenium’s architecture and applicability guides when deciding whether the extra Grid components are justified. Grid architecture · When to use Grid
Keep the Grid private
Do not expose an unauthenticated Grid endpoint to the public internet. Selenium warns that an unprotected Grid can expose internal applications and let third parties run custom binaries. Keep Grid inside the CI network or behind appropriate access controls, and expose only the ports needed by the selected topology. For Hub-and-Node, account for the default Event Bus ports 4442 and 4443 where node communication requires them. Selenium Grid security and setup
Troubleshoot common failures
- Connection refused or name-resolution error: The service may not be ready, the hostname may not resolve from the test container, or the test may be using the wrong port. Poll readiness, verify the configured service hostname and port from the actual test environment, and confirm that the selected containers share a reachable network.
- Tests connect to the wrong endpoint: Use the Standalone service address, Hub address, or Distributed Router address appropriate to the topology. Do not use a node URL just because that node runs a browser.
- Session creation fails: Check that requested browser capabilities are available on registered nodes and that the Grid has capacity. Reduce concurrency and inspect Grid and browser logs to separate a capability mismatch from resource pressure.
- Intermittent startup failures: Replace an arbitrary short sleep with finite readiness polling. Preserve the status response and server logs when the wait times out.
- Tests pass locally but fail in CircleCI: Recheck the executor’s network arrangement. A local
localhostURL or host-side Docker address does not prove that the job’s primary container can reach the same service. - Sessions remain occupied after tests: Ensure teardown quits every driver in a finally/cleanup path, even after an assertion or setup failure.
- CircleCI shows no test results: Confirm the test framework actually writes reports and that the configured
store_test_resultspath points to those files.
Or skip the browser setup
If your task is to capture website screenshots rather than execute interactive Selenium browser tests, ScreenshotNeo is a screenshot API and MCP server for developers. One GET request returns an image or PDF. Cookie banners are accepted and removed before capture, along with supported newsletter popups and chat widgets; bot checks, blank pages, and failed loads are not billed. An MCP server lets AI agents use screenshot tools, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Use the screenshot API docs at screenshotneo.com/docs for request options and setup.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can CircleCI run Selenium tests without a separately managed Grid?
Yes. A small run can use a disposable Standalone service in the job’s reachable network; larger or broader browser setups can use a private shared Grid.
Does Selenium Grid make a slow test suite faster automatically?
No. Parallel execution can help only when there are available slots and sufficient measured resources; actual runtime also depends on test duration and queueing.
