Jump to content

Connect Leeroopedia MCP: Equip your AI agents to search best practices, build plans, verify code, diagnose failures, and look up hyperparameter defaults.

Implementation:DevExpress Testcafe TestCafe Configuration Options

From Leeroopedia
Knowledge Sources
Domains Testing, CI_CD, Web_Automation
Last Updated 2026-02-12 04:00 GMT

Overview

Comprehensive configuration system for TestCafe execution parameters, implemented through OptionNames enum and TestCafeConfiguration class.

Description

TestCafe's configuration system provides 59 distinct options (enumerated in OptionNames) for controlling test execution behavior. The TestCafeConfiguration class extends ConfigurationBase to load settings from .testcaferc.js/.json/.cjs files, merge them with programmatic API options and CLI flags, and prepare them for consumption by the test runner.

The implementation handles:

  • Configuration Loading: Async loading from multiple file formats (JS, JSON, CJS)
  • Option Merging: Hierarchical merging with override tracking
  • Type Coercion: Converting string inputs to proper types (numbers, booleans, objects)
  • Default Values: Applying sensible defaults for all options
  • Validation: Ensuring option values are within valid ranges
  • Browser Resolution: Converting browser strings to BrowserInfo objects

Key configurable parameters include concurrency (parallel browser instances), timeout values (selector, assertion, page load), quarantine mode (flaky test retry), stop-on-first-fail (fail-fast), speed factor (execution delay), and application command (tested app lifecycle management).

Usage

Use this implementation when:

  • Creating .testcaferc.js configuration files for projects
  • Programmatically configuring test runs via runner.run(options)
  • Understanding available CLI flags and their effects
  • Optimizing test execution for CI environments
  • Debugging configuration issues and override behavior

Code Reference

Source Location

  • Repository: testcafe
  • Files:
    • src/configuration/option-names.ts (lines 1-64) - OptionNames enum
    • src/configuration/testcafe-configuration.ts (lines 96-343) - TestCafeConfiguration class

Signature

// OptionNames enum (59 options)
enum OptionNames {
    src = 'src',
    browsers = 'browsers',
    concurrency = 'concurrency',
    speed = 'speed',
    selectorTimeout = 'selectorTimeout',
    assertionTimeout = 'assertionTimeout',
    pageLoadTimeout = 'pageLoadTimeout',
    stopOnFirstFail = 'stopOnFirstFail',
    quarantineMode = 'quarantineMode',
    appCommand = 'appCommand',
    appInitDelay = 'appInitDelay',
    // ... 48 more options
}

// TestCafeConfiguration class
class TestCafeConfiguration extends ConfigurationBase {
    constructor(configFile?: string)
    async init(options?: Dictionary<object>): Promise<void>
    async asyncMergeOptions(options?: Dictionary<object>): Promise<void>
    prepare(): void
    get startOptions(): TestCafeStartOptions
}

Import

// Internal TestCafe usage
import OPTION_NAMES from './configuration/option-names';
import TestCafeConfiguration from './configuration/testcafe-configuration';

// Usage in runner
const config = new TestCafeConfiguration('.testcaferc.js');
await config.init();
config.prepare();

I/O Contract

Inputs

Name Type Required Description
configFile string No Path to config file (.testcaferc.js/.json/.cjs)
options Dictionary No Programmatic options to merge
CLI flags various No Command-line arguments

Outputs

Name Type Description
configuration object Merged and validated configuration object
startOptions TestCafeStartOptions Options for starting TestCafe server
warnings string[] Override and deprecation warnings

Usage Examples

Configuration File: .testcaferc.js

module.exports = {
    // Test source files
    src: ['tests/**/*.test.js'],

    // Target browsers
    browsers: ['chrome:headless', 'firefox:headless'],

    // Concurrency: run 3 tests in parallel
    concurrency: 3,

    // Timeouts (milliseconds)
    selectorTimeout: 10000,      // Wait for elements
    assertionTimeout: 3000,      // Retry assertions
    pageLoadTimeout: 5000,       // Page navigation

    // Speed: 0.01-1.0 (1.0 = normal, 0.5 = 2x slower)
    speed: 1.0,

    // Fail-fast: stop on first failure
    stopOnFirstFail: false,

    // Quarantine mode: retry flaky tests
    quarantineMode: {
        attemptLimit: 5,         // Max 5 attempts
        successThreshold: 2      // Need 2 consecutive successes
    },

    // Screenshots
    screenshots: {
        path: './screenshots',
        takeOnFails: true,
        pathPattern: '${DATE}_${TIME}/${FIXTURE}/${TEST}.png'
    },

    // Reporters
    reporter: [
        { name: 'spec' },
        { name: 'xunit', output: 'reports/junit.xml' }
    ],

    // Start tested application
    appCommand: 'node server.js',
    appInitDelay: 3000,          // Wait 3s after app starts

    // Skip JavaScript errors
    skipJsErrors: true,

    // Disable page caching
    disablePageCaching: true,

    // Browser initialization timeout
    browserInitTimeout: 60000,

    // Test execution timeout (per test)
    testExecutionTimeout: 180000, // 3 minutes

    // Run execution timeout (entire run)
    runExecutionTimeout: 3600000  // 1 hour
};

CLI Usage

# Concurrency
testcafe chrome tests/ --concurrency 5

# Timeouts
testcafe chrome tests/ \
  --selector-timeout 15000 \
  --assertion-timeout 5000 \
  --page-load-timeout 10000

# Quarantine mode
testcafe chrome tests/ --quarantine-mode

# Stop on first fail
testcafe chrome tests/ --stop-on-first-fail

# Speed control (0.01 to 1.0)
testcafe chrome tests/ --speed 0.5

# App command
testcafe chrome tests/ \
  --app "node server.js" \
  --app-init-delay 5000

# Multiple options
testcafe chrome:headless tests/ \
  --concurrency 3 \
  --stop-on-first-fail \
  --screenshots path=./screenshots,takeOnFails=true \
  --reporter spec,xunit:report.xml

Programmatic API

const createTestCafe = require('testcafe');

(async () => {
    const testcafe = await createTestCafe('localhost', 1337, 1338);
    const runner = testcafe.createRunner();

    const failedCount = await runner
        .src(['tests/**/*.js'])
        .browsers(['chrome:headless', 'firefox:headless'])
        .concurrency(3)
        .run({
            // Timeouts
            selectorTimeout: 10000,
            assertionTimeout: 3000,
            pageLoadTimeout: 5000,

            // Execution control
            speed: 1.0,
            stopOnFirstFail: false,

            // Quarantine mode
            quarantineMode: {
                attemptLimit: 5,
                successThreshold: 2
            },

            // Screenshots
            screenshots: {
                path: './screenshots',
                takeOnFails: true
            },

            // App lifecycle
            appCommand: 'node server.js',
            appInitDelay: 3000,

            // Error handling
            skipJsErrors: true,
            skipUncaughtErrors: false
        });

    console.log('Tests failed: ' + failedCount);
    await testcafe.close();
})();

Configuration Merging Example

// .testcaferc.js (lowest priority)
{
    concurrency: 1,
    speed: 1.0,
    stopOnFirstFail: false
}

// Programmatic API (medium priority)
runner.run({
    concurrency: 3,
    speed: 0.5
})

// CLI flags (highest priority)
// --concurrency 5 --stop-on-first-fail

// Final merged configuration:
{
    concurrency: 5,          // From CLI
    speed: 0.5,              // From API
    stopOnFirstFail: true    // From CLI
}

All 59 Option Names

enum OptionNames {
    // Test configuration
    src = 'src',
    browsers = 'browsers',
    concurrency = 'concurrency',

    // Filtering
    filter = 'filter',
    filterTestGrep = 'filter.testGrep',
    filterFixtureGrep = 'filter.fixtureGrep',

    // Reporting
    reporter = 'reporter',

    // Network
    ssl = 'ssl',
    hostname = 'hostname',
    port1 = 'port1',
    port2 = 'port2',
    proxyBypass = 'proxyBypass',

    // Execution control
    speed = 'speed',
    stopOnFirstFail = 'stopOnFirstFail',
    quarantineMode = 'quarantineMode',

    // Timeouts
    selectorTimeout = 'selectorTimeout',
    assertionTimeout = 'assertionTimeout',
    pageLoadTimeout = 'pageLoadTimeout',
    browserInitTimeout = 'browserInitTimeout',
    testExecutionTimeout = 'testExecutionTimeout',
    runExecutionTimeout = 'runExecutionTimeout',
    pageRequestTimeout = 'pageRequestTimeout',
    ajaxRequestTimeout = 'ajaxRequestTimeout',

    // Screenshots
    screenshots = 'screenshots',
    screenshotPath = 'screenshotPath',
    screenshotPathPattern = 'screenshotPathPattern',
    screenshotPathPatternOnFails = 'screenshotPathPatternOnFails',
    takeScreenshotsOnFails = 'takeScreenshotsOnFails',
    disableScreenshots = 'disableScreenshots',

    // Video recording
    videoPath = 'videoPath',
    videoOptions = 'videoOptions',
    videoEncodingOptions = 'videoEncodingOptions',

    // Application lifecycle
    appCommand = 'appCommand',
    appInitDelay = 'appInitDelay',

    // Error handling
    skipJsErrors = 'skipJsErrors',
    skipUncaughtErrors = 'skipUncaughtErrors',

    // Debugging
    debugMode = 'debugMode',
    debugOnFail = 'debugOnFail',
    debugLogger = 'debugLogger',

    // Compilation
    tsConfigPath = 'tsConfigPath',
    compilerOptions = 'compilerOptions',

    // Client-side injection
    clientScripts = 'clientScripts',
    requestHooks = 'requestHooks',

    // Browser behavior
    retryTestPages = 'retryTestPages',
    disablePageReloads = 'disablePageReloads',
    disablePageCaching = 'disablePageCaching',
    disableMultipleWindows = 'disableMultipleWindows',
    experimentalMultipleWindows = 'experimentalMultipleWindows',

    // Protocol configuration
    disableHttp2 = 'disableHttp2',
    disableNativeAutomation = 'disableNativeAutomation',
    disableCrossDomain = 'disableCrossDomain',

    // Advanced
    developmentMode = 'developmentMode',
    cache = 'cache',
    userVariables = 'userVariables',
    v8Flags = 'v8Flags',
    hooks = 'hooks',
    baseUrl = 'baseUrl',
    esm = 'esm',
    customActions = 'customActions'
}

Default Values

// From src/configuration/default-values.ts
const DEFAULTS = {
    selectorTimeout: 10000,        // 10 seconds
    assertionTimeout: 3000,        // 3 seconds
    pageLoadTimeout: 3000,         // 3 seconds
    speed: 1.0,                    // Normal speed
    appInitDelay: 1000,            // 1 second
    concurrency: 1,                // Serial execution
    developmentMode: false,
    retryTestPages: false,
    disableHttp2: false,
    disableNativeAutomation: false,
    disableCrossDomain: false,
    experimentalMultipleWindows: false,
    screenshotThumbnails: true,
    sourceDirectories: ['tests']
};

CI Optimization Example

# Optimized for fast CI feedback
testcafe chrome:headless tests/ \
  --concurrency 5 \
  --stop-on-first-fail \
  --selector-timeout 5000 \
  --assertion-timeout 2000 \
  --page-load-timeout 5000 \
  --skip-js-errors \
  --disable-page-caching \
  --screenshots path=./screenshots,takeOnFails=true \
  --reporter minimal,xunit:junit.xml

Related Pages

Implements Principle

Uses Heuristic

Page Connections

Double-click a node to navigate. Hold to expand connections.
Principle
Implementation
Heuristic
Environment
Retrieved from "https://leeroopedia.com/index.php?title=Implementation:DevExpress_Testcafe_TestCafe_Configuration_Options&oldid=2695"