Implementation:DevExpress Testcafe BrowserConnection

Knowledge Sources	DevExpress_Testcafe TestCafe Docs
Domains	Browser_Communication, Test_Execution
Last Updated	2026-02-12 12:00 GMT

Overview

Concrete tool for managing the lifecycle of a single browser instance's connection to the TestCafe server.

Description

The BrowserConnection class represents and manages the full lifecycle of a connected browser, including opening/closing browsers, heartbeat monitoring, job queue management, status polling, and init script execution. It extends EventEmitter to emit lifecycle events (ready, opened, idle, closing, closed, disconnected, error). It builds communication URLs for the browser client, manages a heartbeat timeout that triggers browser restart on disconnection, serves an idle page, polls for the next test run from a job queue, and delegates browser operations to a BrowserProvider.

Usage

BrowserConnection instances are created internally when a browser connects to TestCafe's gateway. They are not instantiated directly by test authors but are the core abstraction for managing connected browsers.

Code Reference

Source Location

Repository: DevExpress_Testcafe
File: src/browser/connection/index.ts
Lines: 1-671

Signature

export interface BrowserInfo {
    alias: string;
    browserName: string;
    providerName: string;
    provider: BrowserProvider;
    browserOption: unknown;
    userAgentProviderMetaInfo: string;
}

export default class BrowserConnection extends EventEmitter {
    public id: string;
    public browserInfo: BrowserInfo;
    public permanent: boolean;
    public previousActiveWindowId: string | null;
    public allowMultipleWindows: boolean;
    public idleUrl: string;
    public url: string;
    public statusUrl: string;
    public heartbeatUrl: string;
    public initScriptUrl: string;
    public activeWindowIdUrl: string;

    public constructor (
        gateway: BrowserConnectionGateway,
        browserInfo: BrowserInfo,
        permanent: boolean,
        allowMultipleWindows: boolean,
        disableMultipleWindows: boolean,
        messageBus: MessageBus,
        isProxyless: boolean
    );

    public addJob (job: BrowserJob): void;
    public removeJob (job: BrowserJob): void;
    public close (): void;
    public establish (userAgent: string): void;
    public getStatus (isTestDone: boolean): BrowserConnectionStatusResult;
    public processDisconnection (code: number): void;
}

Import

import BrowserConnection from './browser/connection';

I/O Contract

Inputs

Name	Type	Required	Description
gateway	BrowserConnectionGateway	Yes	The gateway that manages HTTP routes for this connection
browserInfo	BrowserInfo	Yes	Browser metadata including alias, name, provider
permanent	boolean	Yes	Whether the connection persists between test runs
allowMultipleWindows	boolean	Yes	Whether multi-window mode is enabled
messageBus	MessageBus	Yes	Event bus for system-wide messaging

Outputs

Name	Type	Description
Events: ready	void	Emitted when the browser is connected and ready
Events: idle	void	Emitted when browser has no more tests to run
Events: disconnected	void	Emitted when the heartbeat timeout expires
getStatus()	BrowserConnectionStatusResult	Returns the next command for the browser

Usage Examples

// Internal usage: creating and managing a browser connection
import BrowserConnection from './browser/connection';

// 1. Connection is created internally by the runner/bootstrapper
const connection = new BrowserConnection(
    gateway,
    browserInfo,
    /* permanent */ false,
    /* allowMultipleWindows */ true,
    /* disableMultipleWindows */ false,
    messageBus,
    /* isProxyless */ false
);

// 2. Listen for connection readiness
connection.once('ready', () => {
    console.log(`Browser ${connection.browserInfo.alias} connected`);
});

// 3. Add a test job to the queue
connection.addJob(browserJob);

// 4. Close the connection
connection.close();

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment