Workflow:DevExpress Testcafe Programmatic Test Execution
| Knowledge Sources | |
|---|---|
| Domains | Testing, Web_Automation, Node_API |
| Last Updated | 2026-02-12 04:00 GMT |
Overview
End-to-end process for running TestCafe tests programmatically via the Node.js API, covering instance creation, runner configuration, test execution, and resource cleanup.
Description
This workflow describes the standard procedure for embedding TestCafe into a Node.js application or script. Instead of using the CLI, tests are configured and executed through the programmatic API. The process starts with importing the createTestCafe factory function, which initializes the Hammerhead proxy server, browser connection gateway, and configuration system. A Runner instance provides a fluent API to set test sources, browsers, reporters, screenshots, video, and other options. Calling runner.run() bootstraps the test execution: compiling test files, opening browsers, distributing tests across browser jobs, and collecting results. The API returns the number of failed tests as a promise, allowing integration with custom orchestration logic, build systems, and testing dashboards.
Usage
Execute this workflow when you need to integrate TestCafe test execution into a custom Node.js script, build tool, or testing framework. This is appropriate when the CLI does not provide sufficient control over the test lifecycle, when you need to programmatically process results, when embedding TestCafe into a larger application, or when building custom tooling around TestCafe.
Execution Steps
Step 1: Create TestCafe instance
Import the createTestCafe factory function from the testcafe package. Call it with a configuration object specifying hostname, ports, SSL options, and other server-level settings. The factory initializes the Hammerhead reverse proxy, binds to the configured network ports, creates the browser connection gateway, and loads configuration from the .testcaferc file if present. The returned TestCafe instance is the entry point for creating runners.
Key considerations:
- The configuration object accepts
hostname,port1,port2,ssl,configFile, and other server options - Ports are automatically assigned if not specified
- An exit hook is registered to close the instance on process termination
- The instance manages the proxy server lifecycle
Step 2: Create a Runner
Call testCafe.createRunner() to obtain a Runner instance, or testCafe.createLiveModeRunner() for live mode with file watching. The Runner provides a fluent (chainable) API for configuring the test run. It creates a Bootstrapper internally that will resolve browsers, compile tests, and prepare all resources when the run is initiated.
Key considerations:
- Each Runner instance represents a single test run configuration
- Multiple runners can be created from the same TestCafe instance
- Live mode runners watch files and re-run on changes
- The Runner emits a
done-bootstrappingevent when browser connections are established
Step 3: Configure the Runner
Chain configuration methods on the Runner to set test sources (.src()), browsers (.browsers()), reporters (.reporter()), concurrency (.concurrency()), screenshots (.screenshots()), video recording (.video()), test filters (.filter()), client scripts (.clientScripts()), compiler options (.compilerOptions()), proxy settings (.useProxy()), and a companion application (.startApp()).
Key considerations:
.src()accepts file paths, directories, or glob patterns.browsers()accepts browser names, paths, or BrowserConnection objects.reporter()accepts reporter name strings, objects with name and output, or factory functions.filter()accepts a predicate function receiving test name, fixture name, fixture path, test metadata, and fixture metadata- Configuration file values serve as defaults; API calls override them
Step 4: Execute the test run
Call runner.run() with an optional run options object to start test execution. The Runner triggers the Bootstrapper, which compiles test files, establishes browser connections, loads client scripts, and creates browser jobs. Tests are distributed across browser instances and executed. The method returns a promise that resolves to the number of failed tests. Run options include skipJsErrors, skipUncaughtErrors, quarantineMode, debugMode, debugOnFail, selectorTimeout, assertionTimeout, pageLoadTimeout, speed, and stopOnFirstFail.
Key considerations:
- The returned number represents failed test count (0 = all passed)
- Errors during bootstrapping reject the promise with a descriptive error
- The Bootstrapper validates native automation support per browser
- Tests are queued and distributed across browser connections with optional concurrency
Step 5: Close the TestCafe instance
After the test run completes, call testCafe.close() to shut down the proxy server, close all browser connections, and release network ports. This should be called in a finally block to ensure cleanup even when tests fail or errors occur.
Key considerations:
- Always close the TestCafe instance to avoid port leaks
- Use try/finally to ensure cleanup on both success and failure
- The exit hook registered during creation also calls close, but explicit cleanup is preferred
- After closing, the TestCafe instance cannot be reused