Implementation:DevExpress Testcafe Chrome Headless Config
| Knowledge Sources | |
|---|---|
| Domains | Testing, CI_CD, Web_Automation |
| Last Updated | 2026-02-12 04:00 GMT |
Overview
Configuration parser for Chrome browser with headless mode, device emulation, and user profile management provided by TestCafe's built-in Chrome browser provider.
Description
This module provides a cached factory function that parses Chrome browser configuration strings and returns configuration objects. It handles three main modes: headless (no GUI), userProfile (persistent browser state), and emulation (device simulation). The parser extracts modes and options from colon-separated strings, applies default dimensions for headless mode (1280x800), resolves device names to specifications from the device-specs library, and caches results for performance.
The configuration supports:
- Headless Mode: Automatic dimension defaults, required Chrome flags
- Device Emulation: Mobile device simulation with proper viewport, user agent, and touch support
- User Profiles: Persistent cookies, localStorage, and browser state
- Custom Arguments: Pass-through of arbitrary Chrome command-line flags
- CDP Port: Chrome DevTools Protocol debugging port specification
Usage
Use this implementation when:
- Configuring TestCafe to run Chrome in headless mode for CI
- Emulating mobile devices (iPhone, iPad, Android phones)
- Running tests with persistent browser profiles
- Debugging tests with Chrome DevTools Protocol
- Specifying custom Chrome launch arguments
Code Reference
Source Location
- Repository: testcafe
- File: src/browser/provider/built-in/dedicated/chrome/config.js
- Lines: 1-144
Signature
// Default export - cached factory function
export default function chromeConfig(configString: string): Config
// Internal functions
function parseModes(modesStr: string, userArgs: object): { modes, optionsString }
function parseOptions(str: string, useDefaultDimensions: boolean): Options
function getDeviceBasedOptions(deviceName: string, orientation: string): DeviceOptions
function getNewConfig(configString: string): Config
Import
// Internal to TestCafe - used by Chrome browser provider
import chromeConfig from './browser/provider/built-in/dedicated/chrome/config';
// Usage in TestCafe CLI:
// testcafe chrome:headless tests/
// testcafe "chrome:emulation:device=iPhone X" tests/
// testcafe "chrome:headless --window-size=1920,1080" tests/
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| configString | string | Yes | Browser configuration (e.g., "chrome:headless:emulation") |
Outputs
| Name | Type | Description |
|---|---|---|
| Config | object | Configuration object with modes and options |
| config.headless | boolean | Whether headless mode is enabled |
| config.userProfile | boolean | Whether to use persistent user profile |
| config.emulation | boolean | Whether device emulation is enabled |
| config.width | number | Viewport width in pixels |
| config.height | number | Viewport height in pixels |
| config.deviceName | string | Device name if emulation enabled |
| config.mobile | boolean | Whether mobile mode is enabled |
| config.userAgent | string | Custom user agent string |
| config.userArgs | string | Custom Chrome command-line arguments |
Usage Examples
Basic Headless Mode
# Uses default 1280x800 resolution
testcafe chrome:headless tests/sample.js
Headless with Custom Arguments
testcafe "chrome:headless --no-sandbox --disable-gpu" tests/
Device Emulation
# Emulate iPhone X in portrait mode
testcafe "chrome:emulation:device=iPhone X" tests/
# Emulate with custom orientation
testcafe "chrome:emulation:device=iPad:orientation=horizontal" tests/
Custom Dimensions
testcafe "chrome:headless:emulation:width=1920:height=1080" tests/
Programmatic Configuration
// Internal usage within TestCafe
import chromeConfig from './browser/provider/built-in/dedicated/chrome/config';
const config1 = chromeConfig('chrome:headless');
// Returns: { headless: true, userProfile: false, emulation: true,
// width: 1280, height: 800, userArgs: '' }
const config2 = chromeConfig('chrome:emulation:device=iPhone X');
// Returns: { headless: false, emulation: true, mobile: true,
// deviceName: 'iPhone X', width: 375, height: 812,
// userAgent: 'Mozilla/5.0 (iPhone...)...' }
const config3 = chromeConfig('chrome:headless --window-size=1024,768');
// Returns: { headless: true, userArgs: '--window-size=1024,768',
// width: 1280, height: 800 }
Configuration Object Structure
// Constants
const HEADLESS_DEFAULT_WIDTH = 1280;
const HEADLESS_DEFAULT_HEIGHT = 800;
const AVAILABLE_MODES = ['userProfile', 'headless', 'emulation'];
// Returned Config type
interface Config {
userArgs: string; // Custom Chrome flags
path?: string; // Custom Chrome binary path
headless: boolean; // Headless mode flag
userProfile: boolean; // Use persistent profile
emulation: boolean; // Device emulation enabled
deviceName?: string; // Device name (if emulation)
mobile?: boolean; // Mobile device flag
orientation?: string; // 'vertical' | 'horizontal'
touch?: boolean; // Touch events support
width: number; // Viewport width
height: number; // Viewport height
scaleFactor?: number; // Device pixel ratio
userAgent?: string; // Custom user agent
cdpPort?: string; // Chrome DevTools Protocol port
}
Cache Behavior
// Configuration parsing is cached for performance
const config1 = chromeConfig('chrome:headless'); // Parses and caches
const config2 = chromeConfig('chrome:headless'); // Returns cached result
const config3 = chromeConfig('chrome:headless:emulation'); // New parse
// Cache key is the entire config string
// Identical strings return same object reference
console.log(config1 === config2); // true
Related Pages
Implements Principle
Requires Environment
Uses Heuristic
Page Connections
Double-click a node to navigate. Hold to expand connections.
Principle
Implementation
Heuristic
Environment