Workflow:DevExpress Testcafe CLI Test Execution
| Knowledge Sources | |
|---|---|
| Domains | Testing, CLI, Web_Automation |
| Last Updated | 2026-02-12 04:00 GMT |
Overview
End-to-end process for executing TestCafe tests from the command line, covering installation, browser selection, reporter configuration, and advanced execution options.
Description
This workflow describes the standard procedure for running TestCafe tests using the testcafe CLI command. The process begins with installing TestCafe globally or as a project dependency, then invoking the CLI with a browser target and test source files. The CLI parses arguments, loads configuration from .testcaferc.json/.js/.cjs, creates a TestCafe server instance, resolves browser providers, compiles test files, establishes browser connections, and executes the test suite. Results are reported through configurable reporter plugins and the process exits with a failure count code.
Usage
Execute this workflow when you want to run existing TestCafe test files against one or more browsers from a terminal or shell script. You have test files written in JavaScript, TypeScript, or CoffeeScript and need to execute them with specific browser, reporter, screenshot, video, or concurrency configurations.
Execution Steps
Step 1: Install TestCafe
Install TestCafe as a global npm package or as a project devDependency. The global install makes the testcafe command available system-wide. The local install allows version pinning and is preferred for CI environments. The CLI entry point resolves to a local installation first if one exists in the current working directory.
Key considerations:
- Requires Node.js version 16 or higher
- Global install:
npm install -g testcafe - Local install:
npm install --save-dev testcafe - No WebDriver or browser plugins required
Step 2: Select target browsers
Specify one or more browser targets as positional arguments to the testcafe command. Browsers can be specified by name (e.g., chrome, firefox, edge, safari), with mode suffixes (e.g., chrome:headless, firefox:headless), with device emulation (e.g., chrome:emulation:device=iPhone 12), by path to executable, or as remote for external browser connections. The keyword all runs tests in all locally installed browsers.
Key considerations:
- Browser provider plugins extend support to cloud platforms like SauceLabs and BrowserStack
- Remote browsers display a connection URL and optional QR code
- Multiple browsers can be specified separated by commas
- Browser-specific arguments can be appended (e.g.,
chrome --window-size=1280,720)
Step 3: Specify test sources
Provide file paths or glob patterns as arguments after the browser list. TestCafe supports .js, .ts, .jsx, .tsx, .cjs, .mjs, .coffee, and .testcafe (raw JSON) file extensions. Directories are recursively scanned for test files. Glob patterns allow flexible file selection.
Key considerations:
- Test files are compiled by the appropriate compiler (ES-next via Babel, TypeScript, CoffeeScript, or Raw JSON)
- The
--srcoption can also be specified in the configuration file - Filters can narrow execution to specific tests or fixtures by name, grep pattern, or metadata
Step 4: Configure reporters and output
Specify reporters to format test results using the --reporter flag or configuration file. The default reporter writes to stdout. Multiple reporters can be active simultaneously, each writing to stdout or a file. Custom reporter plugins follow the testcafe-reporter-{name} naming convention and are auto-discovered from npm.
Key considerations:
- Built-in reporters:
spec(default),list,minimal,xunit,json - Reporter with file output:
--reporter xunit:report.xml - Multiple reporters:
--reporter spec,xunit:report.xml - No two reporters can write to the same output stream
Step 5: Configure screenshots and video
Enable screenshot capture on test failures and optionally for all tests using the --screenshots flag or configuration. Screenshots are saved with configurable path patterns that can include test name, browser, date, and index placeholders. Video recording captures the full browser session using FFmpeg and supports per-test or single-file modes.
Key considerations:
- Screenshot path patterns use
${DATE},${TEST},${USERAGENT},${BROWSER},${FILE_INDEX}placeholders - Video requires FFmpeg to be installed and accessible
- Video encoding options (framerate, aspect ratio) are configurable
--video-options failedOnly=truerecords only failing tests
Step 6: Set execution options and run
Configure execution parameters including concurrency (parallel browser instances), timeouts (selector, assertion, page load), speed (throttle factor 0.01-1), quarantine mode (retry failing tests), debug mode, and stop-on-first-fail. These can be set via CLI flags or the configuration file. Invoke the command and TestCafe bootstraps the test run: compiles tests, opens browsers, executes the suite, reports results, and exits with a code equal to the number of failed tests.
Key considerations:
- Concurrency opens N instances of each browser for parallel test distribution
- Configuration file (
.testcaferc.json) provides defaults that CLI flags override - Live mode (
--live) watches for file changes and re-runs tests automatically - Proxy settings (
--proxy) route browser traffic through an HTTP proxy - The exit code equals the number of failed tests (0 = all passed)