Selenium with Docker: Containers for Browsers and Tests
Why Docker?
- Same browser version on every computer and in CI
- Start or destroy a Grid in seconds
- No browser installation on build servers
- Easy scaling: run 10 Chrome containers
Requirement: Install Docker Desktop (Windows, macOS) or Docker Engine (Linux).
One Chrome in One Command
bash
docker run -d -p 4444:4444 -p 7900:7900 --shm-size="2g" selenium/standalone-chrome:latest
| Part | Meaning |
|---|---|
-p 4444:4444 | Grid / WebDriver address |
-p 7900:7900 | Watch the browser live at http://localhost:7900 (noVNC, password secret) |
--shm-size="2g" | Shared memory. Chrome crashes in containers without enough |
selenium/standalone-chrome | Image with Grid + Chrome. Others: standalone-firefox, standalone-edge |
Tip: for repeatable pipelines use a specific version tag instead of latest.
python
from selenium import webdriver
options = webdriver.ChromeOptions()
driver = webdriver.Remote("http://localhost:4444", options=options)
driver.get("https://www.selenium.dev")
print(driver.title)
driver.quit()
Grid with Several Browsers: docker compose
yaml
# docker-compose.yml
services:
selenium-hub:
image: selenium/hub:latest
ports:
- "4444:4444"
- "4442:4442"
- "4443:4443"
chrome:
image: selenium/node-chrome:latest
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
- SE_EVENT_BUS_PUBLISH_PORT=4442
- SE_EVENT_BUS_SUBSCRIBE_PORT=4443
- SE_NODE_MAX_SESSIONS=4
deploy:
replicas: 2
firefox:
image: selenium/node-firefox:latest
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
- SE_EVENT_BUS_PUBLISH_PORT=4442
- SE_EVENT_BUS_SUBSCRIBE_PORT=4443
bash
docker compose up -d
docker compose ps
# open http://localhost:4444 to see the Grid
docker compose dow
Run Tests Inside a Container
dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["pytest", "-n", "4", "--remote=http://selenium-hub:4444", "--headless"]
yaml
tests:
build: .
depends_on:
- selenium-hub
- chrome
environment:
- GRID_URL=http://selenium-hub:4444
volumes:
- ./reports:/app/reports
Inside the compose network the hub address is the service name selenium-hub, not localhost.
Debugging in Docker
- Watch the browser: use the debug image tag or open noVNC on port 7900
- Take screenshots on failure (see the pytest lessons)
docker logs <container>for driver and browser errors- If Chrome crashes with
DevToolsActivePort file doesn't exist, increaseshm_sizeor add--disable-dev-shm-usageand--no-sandboxwhen you run Chrome yourself in a container
Video Recording
The project also publishes a selenium/video image that records each test session as a video, which is very helpful when a test fails only in CI.
Keep versions pinned: Use one tag such as
selenium/standalone-chrome:4.x in your repository so every run is repeatable. Update on purpose.
Conclusion
Docker gives you a throw-away Grid with known browser versions. Use standalone-chrome for quick runs, docker compose for hub and nodes and shm_size to avoid browser crashes.
Quick Summary: docker run selenium/standalone-chrome; compose = hub + nodes; tests use the hub service name.

