Environment:DevExpress Testcafe Docker Xvfb Container
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, CI_CD, Containerization |
| Last Updated | 2026-02-12 03:30 GMT |
Overview
Alpine Linux Docker container with Xvfb virtual display, Chromium, Firefox, and fluxbox window manager for headless TestCafe test execution in CI.
Description
The official TestCafe Docker image provides a fully self-contained headless testing environment based on Alpine Linux 3.23. The container entry point script (`testcafe-docker.sh`) initializes a dbus session daemon, starts Xvfb (X Virtual Framebuffer) with configurable screen resolution, launches the fluxbox window manager, and then runs TestCafe on ports 1337 and 1338. This allows running non-headless browser modes inside containers where no physical display exists. The container includes both Chromium and Firefox browsers, enabling cross-browser testing without host-level browser installation.
Usage
Use this environment for CI/CD pipelines that require browser testing without a GUI, or for local reproducible test execution in an isolated container. This is the recommended setup for GitHub Actions, GitLab CI, Jenkins, and other CI platforms. The Docker_Xvfb_Entry implementation depends on this environment.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Host OS | Any Docker-capable OS | Linux, macOS, Windows with Docker Desktop |
| Software | Docker Engine | Or Podman as alternative |
| Ports | 1337, 1338 | Exposed by container for TestCafe proxy server |
| Disk | ~500MB | Alpine base + browsers + Node.js |
Dependencies
Container Packages (Alpine)
- `nodejs` (Node.js runtime)
- `npm` (package manager)
- `chromium` + `chromium-lang` (Chromium browser with language packs)
- `firefox` (Firefox browser)
- `xvfb` (X Virtual Framebuffer)
- `xwininfo` (X11 window info utility)
- `dbus` (message bus daemon)
- `eudev` (device manager)
- `ttf-freefont` (fonts for page rendering)
- `fluxbox` (lightweight window manager)
- `procps` (process utilities)
- `tzdata` (timezone data)
- `libevent` (event notification library)
Credentials
The following environment variables can be set to customize container behavior:
- `SCREEN_WIDTH`: Xvfb screen width (default: 1280)
- `SCREEN_HEIGHT`: Xvfb screen height (default: 720)
Quick Install
# Pull and run the official TestCafe Docker image
docker run -v $(pwd)/tests:/tests testcafe/testcafe chromium /tests/**/*.js
# With custom screen resolution
docker run -e SCREEN_WIDTH=1920 -e SCREEN_HEIGHT=1080 \
-v $(pwd)/tests:/tests testcafe/testcafe chromium /tests/**/*.js
Code Evidence
Docker entrypoint script from `docker/testcafe-docker.sh:1-9`:
#!/bin/sh
XVFB_SCREEN_WIDTH=${SCREEN_WIDTH-1280}
XVFB_SCREEN_HEIGHT=${SCREEN_HEIGHT-720}
dbus-daemon --session --fork
Xvfb :1 -screen 0 "${XVFB_SCREEN_WIDTH}x${XVFB_SCREEN_HEIGHT}x24" >/dev/null 2>&1 &
export DISPLAY=:1.0
fluxbox >/dev/null 2>&1 &
node /usr/local/lib/node_modules/testcafe/bin/testcafe-with-v8-flag-filter.js --ports 1337,1338 "$@"
Dockerfile package installation from `docker/Dockerfile:13-15`:
RUN apk --no-cache $ALPINE_REPOS upgrade && \
apk --no-cache $ALPINE_REPOS add \
libevent nodejs npm chromium chromium-lang firefox xwininfo xvfb dbus eudev ttf-freefont fluxbox procps tzdata
Container detection used by Chrome provider from `src/browser/provider/built-in/dedicated/chrome/runtime-info.ts:19`:
this.isContainerized = isDocker() || isPodman();
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Xvfb failed to start` | Missing Xvfb package or display conflict | Ensure `xvfb` is installed; check no other process uses `:1` |
| Chrome sandbox error | Container missing `--no-sandbox` flag | TestCafe auto-detects containers and adds the flag |
| Font rendering issues | Missing font packages | Install `ttf-freefont` or other font packages |
| Port 1337/1338 in use | Port conflict with host | Map different ports with `-p 8080:1337` |
Compatibility Notes
- Alpine Linux: Uses edge repositories for latest browser versions. Base image is Alpine 3.23.
- Podman: Container detection works with both Docker and Podman via `is-docker` and `is-podman` packages.
- Non-root user: Container runs as unprivileged `user` account (created in Dockerfile).
- Xvfb color depth: Fixed at 24-bit color depth for accurate screenshot capture.