Environment:DevExpress Testcafe Chrome Browser
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Browser_Automation |
| Last Updated | 2026-02-12 03:30 GMT |
Overview
Google Chrome or Chromium browser environment with Chrome DevTools Protocol (CDP) support for TestCafe test execution, screenshots, and video capture.
Description
TestCafe communicates with Chrome/Chromium browsers via the Chrome DevTools Protocol (CDP) using the `chrome-remote-interface` npm package. The browser provider handles lifecycle management (open, close, resize), device emulation, screenshot capture, and video frame capture. When running inside Docker or Podman containers, additional Chrome flags (`--no-sandbox`, `--disable-dev-shm-usage`, `--disable-gpu`) are automatically applied. The provider supports headless mode (using `--headless=new` for Chrome/Chromium and `--headless` for other Chromium-based browsers), user profile isolation via temporary profile directories, and native automation mode.
Usage
Required for any test execution targeting Chrome or Chromium browsers. This is the primary browser target for headless CI testing. Used by the Chrome_Headless_Config implementation for parsing browser configuration strings and the BrowserProviderPool_GetBrowserInfo implementation for resolving browser aliases to provider instances.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, Windows | All major platforms supported |
| Browser | Google Chrome or Chromium | Any recent version with CDP support |
| Network | Local TCP port for CDP | Dynamically allocated unless using user profile |
| Display | X11 display or headless mode | Linux requires DISPLAY env var or `--headless` flag |
Dependencies
System Packages
- `chromium` or `google-chrome` (browser binary)
- `xvfb` (virtual framebuffer, Linux headless without `--headless` flag)
NPM Packages
- `chrome-remote-interface` >= 0.32.2 (CDP client)
- `devtools-protocol` = 0.0.1109433 (protocol type definitions)
- `testcafe-browser-tools` = 2.0.26 (window management utilities)
Credentials
No credentials required for Chrome browser operation.
Quick Install
# Linux (Ubuntu/Debian)
apt-get install -y chromium-browser
# macOS (Homebrew)
brew install --cask google-chrome
# Alpine (Docker)
apk add chromium
Code Evidence
Container detection and flag injection from `src/browser/provider/built-in/dedicated/chrome/runtime-info.ts:19`:
this.isContainerized = isDocker() || isPodman();
Containerized Chrome flags from `src/browser/provider/built-in/dedicated/chrome/build-chrome-args.js:1`:
export const CONTAINERIZED_CHROME_FLAGS = ['--no-sandbox', '--disable-dev-shm-usage', '--disable-gpu'];
Headless mode detection from `src/browser/provider/built-in/dedicated/chrome/build-chrome-args.js:4`:
const headlessMode = ['chrome', 'chromium'].includes(browserName) ? '--headless=new' : '--headless';
DISPLAY environment variable check from `src/utils/detect-display.ts:1-3`:
export default function (): boolean {
return !!process.env.DISPLAY;
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| Browser connection timeout | Chrome failed to start within init timeout | Increase `browserInitTimeout` option; check Chrome is installed |
| `No sandbox` crash on Linux | Missing `--no-sandbox` in container | TestCafe auto-adds this flag in Docker/Podman; verify container detection |
| CDP connection refused | Chrome not listening on expected port | Check for port conflicts; ensure Chrome started successfully |
| No DISPLAY on Linux | Missing X11 display server | Use `--headless` flag or start Xvfb virtual framebuffer |
Compatibility Notes
- Headless mode: Chrome/Chromium use `--headless=new` (new headless architecture); other Chromium-based browsers use `--headless` (legacy).
- Docker/Podman: Automatically detected via `is-docker` and `is-podman` packages; containerized flags injected automatically.
- macOS: Chrome process cleanup requires explicit `stopLocalChrome()` call after close.
- Linux: Chrome may require two SIGTERM signals to fully close (noted in `src/browser/provider/built-in/dedicated/chrome/local-chrome.js:56`).
- Native Automation: Only available for local browsers; remote browsers cannot use CDP-based native automation mode.