Implementation:DevExpress Testcafe CreateTestCafe Factory

Knowledge Sources	TestCafe TestCafe Docs
Domains	Testing, Web_Automation
Last Updated	2026-02-12 04:00 GMT

Overview

Concrete factory function for creating TestCafe instances that manage proxy servers, browser connections, and test execution configuration provided by TestCafe.

Description

The createTestCafe function is the primary entry point for programmatic TestCafe usage. It accepts configuration in two forms: a modern object-based form with named options, or a legacy positional argument form for backward compatibility. The function resolves configuration from multiple sources (arguments, config files, defaults), validates port availability, constructs the core TestCafe instance with proxy and browser gateway, and registers an exit hook for automatic cleanup on process termination.

The function uses lazy-loading via import-lazy to defer loading heavy dependencies (testcafe-hammerhead proxy, CoffeeScript compiler) until actually needed. This reduces startup time for processes that conditionally create TestCafe instances.

Usage

Use createTestCafe at the start of programmatic test execution to initialize the TestCafe runtime. Call it once per test session, then create runners from the returned instance. Always call the close method on the instance in a finally block to ensure proper resource cleanup.

Code Reference

Source Location

Repository: testcafe
File: src/index.js
Lines: 47-69

Signature

async function createTestCafe(...args): Promise<TestCafe>

// Modern form (object-based):
createTestCafe({
    hostname?: string,
    port1?: number,
    port2?: number,
    ssl?: { key: string, cert: string },
    developmentMode?: boolean,
    retryTestPages?: boolean,
    cache?: boolean,
    configFile?: string
}): Promise<TestCafe>

// Legacy form (positional):
createTestCafe(
    hostname?: string,
    port1?: number,
    port2?: number,
    ssl?: object,
    developmentMode?: boolean,
    retryTestPages?: boolean,
    cache?: boolean,
    configFile?: string
): Promise<TestCafe>

Import

// CommonJS
const createTestCafe = require('testcafe');

// ES Modules
import createTestCafe from 'testcafe';

I/O Contract

Inputs

Name	Type	Required	Description
hostname	string	No	Hostname for TestCafe proxy server (default: localhost)
port1	number	No	Primary proxy port (default: auto-assigned)
port2	number	No	Secondary proxy port (default: auto-assigned)
ssl	object	No	SSL certificate configuration with key and cert paths
developmentMode	boolean	No	Enable development mode with additional debugging (default: false)
retryTestPages	boolean	No	Retry test page loads on failure (default: false)
cache	boolean	No	Enable request caching (default: true)
configFile	string	No	Path to TestCafe configuration file (default: .testcaferc.json)

Outputs

Name	Type	Description
testcafe	Promise<TestCafe>	Promise resolving to TestCafe instance with proxy, browser gateway, and configuration

Usage Examples

Basic Usage with Object Configuration

const createTestCafe = require('testcafe');

(async () => {
    const testcafe = await createTestCafe({
        hostname: 'localhost',
        port1: 1337,
        port2: 1338
    });

    try {
        const runner = testcafe.createRunner();
        const failedCount = await runner
            .src('tests/**/*.js')
            .browsers('chrome')
            .run();

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

Using Configuration File

const createTestCafe = require('testcafe');

(async () => {
    const testcafe = await createTestCafe({
        configFile: './testcafe-config.json'
    });

    try {
        const runner = testcafe.createRunner();
        await runner
            .src('tests/**/*.js')
            .browsers('chrome', 'firefox')
            .reporter('spec')
            .run();
    }
    finally {
        await testcafe.close();
    }
})();

Development Mode with SSL

const createTestCafe = require('testcafe');
const fs = require('fs');

(async () => {
    const testcafe = await createTestCafe({
        hostname: 'my-test-server.local',
        ssl: {
            key: fs.readFileSync('key.pem'),
            cert: fs.readFileSync('cert.pem')
        },
        developmentMode: true,
        retryTestPages: true
    });

    try {
        const runner = testcafe.createRunner();
        await runner
            .src('tests/**/*.js')
            .browsers('chrome:headless')
            .run();
    }
    finally {
        await testcafe.close();
    }
})();

Legacy Positional Arguments (Deprecated)

const createTestCafe = require('testcafe');

(async () => {
    // Legacy form: hostname, port1, port2, ssl, developmentMode
    const testcafe = await createTestCafe('localhost', 1337, 1338);

    try {
        const runner = testcafe.createRunner();
        await runner
            .src('tests/**/*.js')
            .browsers('chrome')
            .run();
    }
    finally {
        await testcafe.close();
    }
})();

Implementation Details

Internal Flow

Calls getConfiguration(args) to parse arguments and create TestCafeConfiguration instance
Validates and allocates ports using getValidPort() for both port1 and port2
Merges user variables from configuration into global userVariables object
Constructs new TestCafe(configuration) which initializes hammerhead Proxy and BrowserConnectionGateway
Registers exit hook via async-exit-hook that calls testcafe.close() on process termination
Returns the initialized TestCafe instance

Key Dependencies

testcafe-hammerhead: HTTP proxy for intercepting and modifying browser traffic
import-lazy: Lazy-loading module system to defer heavy imports
async-exit-hook: Process exit handler for graceful cleanup
coffeescript: CoffeeScript compiler support (loaded eagerly for stack trace support)

Related Pages

Implements Principle

Principle:DevExpress_Testcafe_TestCafe_Instance_Creation

Related Implementations

Requires Environment

Environment:DevExpress_Testcafe_Node_Runtime

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment