Running Selenium Grid in GitHub Actions

Spin up a Selenium Grid with service containers and point your tests at it in CI.

Selenium Grid lets you run tests against real browsers in containers. In GitHub Actions you can use the standalone Selenium images as service containers, exposing the WebDriver endpoint at localhost:4444 for your test code to connect to.

What you need

A test suite that talks to a remote WebDriver URL.
A Selenium standalone image (selenium/standalone-chrome) as a service.
The exposed port 4444 mapped to the host.

The workflow

Run Selenium as a service container and connect tests to it.

.github/workflows/e2e.yml

jobs:
  e2e:
    runs-on: ubuntu-latest
    services:
      selenium:
        image: selenium/standalone-chrome:latest
        ports:
          - 4444:4444
        options: --shm-size=2g
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
        env:
          SELENIUM_REMOTE_URL: http://localhost:4444/wd/hub

Common gotchas

Chrome crashes in containers without --shm-size=2g due to a tiny default /dev/shm.
Tests may start before the grid is ready - poll the /status endpoint first.
Service containers only run on Linux runners, not macOS or Windows.

Key takeaways

Run Selenium standalone images as service containers.
Set --shm-size=2g to avoid Chrome crashes in containers.
Point tests at http://localhost:4444/wd/hub and wait for readiness.