Heuristic:DevExpress Testcafe Concurrency Factor Limit
| Knowledge Sources | |
|---|---|
| Domains | Performance, CI_CD |
| Last Updated | 2026-02-12 03:30 GMT |
Overview
Concurrency factor above 3 triggers a resource warning; default is 1. Tune based on available CPU cores and memory.
Description
TestCafe supports running tests concurrently across multiple browser instances via the `--concurrency` (or `-c`) CLI flag. The default concurrency is 1 (sequential). When concurrency exceeds 3, TestCafe adds a diagnostic hint to browser connection error messages warning that the host machine may not have sufficient resources. This threshold is a heuristic — the actual safe concurrency depends on the machine's CPU count, available RAM, and whether browsers are running in headless mode (which uses less memory).
Usage
Apply this heuristic when configuring CI test parallelism or debugging browser connection timeouts in concurrent test runs. If browser initialization fails with concurrency > 3, reduce concurrency or allocate more resources to the CI runner. On powerful machines (8+ cores, 16GB+ RAM), concurrency up to 6-8 may work fine.
The Insight (Rule of Thumb)
- Action: Set concurrency via `--concurrency N` CLI flag or `concurrency` runner option. Keep at or below 3 for standard CI runners.
- Value: Default: 1. Warning threshold: > 3. Each browser instance requires ~200-500MB RAM in headless mode.
- Trade-off: Higher concurrency reduces total test time but increases memory usage and risk of browser connection timeouts. Each additional browser instance competes for CPU, memory, and I/O.
- Browser init timeouts: Local browsers get 2 minutes to initialize; remote browsers get 6 minutes. These can be increased with `--browser-init-timeout`.
Reasoning
Each concurrent browser instance spawns a separate process consuming CPU and memory. In headless Chrome, each instance uses roughly 200-500MB RAM. On a standard CI runner (2 vCPUs, 7GB RAM), concurrency of 3 uses ~1.5GB just for browsers plus TestCafe's Node.js process. Exceeding available resources causes browser startup timeouts, which manifest as cryptic connection errors. The hardcoded threshold of 3 provides a conservative default warning, as most CI environments have 2-4 cores.
Code Evidence
Concurrency factor upperbound from `src/browser/connection/get-hints.ts:10-11`:
// NOTE: hint about too high concurrency factor will be added to the error after exceeding this value
const CONCURRENCY_FACTOR_UPPERBOUND = 3;
Warning trigger from `src/browser/connection/get-hints.ts:32-33`:
if (opts.concurrency > CONCURRENCY_FACTOR_UPPERBOUND)
hints.push(renderTemplate(TEMPLATES[BrowserConnectionErrorHint.TooHighConcurrencyFactor], opts.concurrency));
Default concurrency value from `src/configuration/default-values.ts:14`:
export const DEFAULT_CONCURRENCY_VALUE = 1;
Browser init timeouts from `src/utils/browser-connection-timeouts.js:10-11`:
export const LOCAL_BROWSER_INIT_TIMEOUT = 2 * 60 * 1000; // 2 minutes
export const REMOTE_BROWSER_INIT_TIMEOUT = 6 * 60 * 1000; // 6 minutes