Implementation:DevExpress Testcafe FirefoxMarionetteClient

Knowledge Sources	DevExpress_Testcafe TestCafe Docs
Domains	Browser Automation, Marionette Protocol
Last Updated	2026-02-12 12:00 GMT

Overview

MarionetteClient is a TCP socket-based client that communicates with Firefox via the Marionette remote protocol, providing browser control primitives such as session management, script execution, screenshots, and window resizing.

Description

The MarionetteClient class in src/browser/provider/built-in/dedicated/firefox/marionette-client/index.js implements a low-level client for the Marionette protocol. It opens a raw TCP socket to a Firefox instance, performs length-prefixed JSON message framing (header:body), manages packet sequencing with incrementing packet numbers, and correlates responses to requests. The class handles connection retries with a 30-second timeout, maintains a buffer for partial TCP reads, and provides high-level methods for session creation, JavaScript execution, screenshot capture, window sizing, and graceful shutdown. Window handle tracking ensures commands target the correct TestCafe-managed tab by matching the window title to the active window ID.

Usage

The Firefox browser provider creates a MarionetteClient instance during openBrowser to control the Firefox process. It is an internal implementation detail of the Firefox dedicated provider and is not used directly by TestCafe end users.

Code Reference

Source Location

Repository: DevExpress_Testcafe
File: src/browser/provider/built-in/dedicated/firefox/marionette-client/index.js
Lines: 1-268

Signature

class MarionetteClient {
    constructor (port = 2828, runtimeInfo, host = '127.0.0.1')

    // Properties
    currentPacketNumber: number
    events: EventEmitter
    port: number
    host: string
    socket: Socket
    buffer: Buffer
    getPacketPromise: Promise
    sendPacketPromise: Promise
    protocolInfo: { applicationType: string, marionetteProtocol: string }
    sessionInfo: object | null

    // Getter
    get activeWindowId (): string

    // Private methods
    async _attemptToConnect (port, host): Promise<boolean>
    async _connectSocket (port, host): Promise<void>
    async _writeSocket (message): Promise<void>
    _handleNewData (data): void
    _getPacket (): Promise<{ length: number, body: any }>
    _sendPacket (payload): Promise<void>
    _throwMarionetteError (error): never
    async _switchToWindow (windowHandle): Promise<void>
    async _getActiveWindowHandle (): Promise<string | null>
    async _ensureActiveWindow (): Promise<void>
    async _request (packet): Promise<any>
    async _getResponse (packet): Promise<any>
    async _getScreenshotRawData (fullPage = false): Promise<object>

    // Public API
    async connect (): Promise<void>
    dispose (): void
    async executeScript (code): Promise<object>
    async getScreenshotData (fullPage): Promise<Buffer>
    async setWindowSize (width, height): Promise<void>
    async quit (): Promise<void>
    async closeBrowserChildWindow (): Promise<void>
}

Import

import MarionetteClient from '../browser/provider/built-in/dedicated/firefox/marionette-client/index.js';

I/O Contract

Constructor

Input	Type	Default	Description
port	number	2828	TCP port where the Firefox Marionette server listens
runtimeInfo	object	(required)	Runtime context object containing activeWindowId and other browser state
host	string	'127.0.0.1'	Host address of the Firefox instance

connect()

Output	Type	Description
(side effect)	void	Opens socket, reads protocol info packet, starts a new Marionette session (populates protocolInfo and sessionInfo)

executeScript(code)

Input	Type	Description
code	string	JavaScript code string to execute in the browser context; wrapped as return (`)()`

Output	Type	Description
result	object	The Marionette response body (index [3] of the response array)

getScreenshotData(fullPage)

Input	Type	Description
fullPage	boolean	When true, captures the entire scrollable page; when false, captures the visible viewport

Output	Type	Description
buffer	Buffer	PNG screenshot data decoded from the base64 Marionette response

setWindowSize(width, height)

Input	Type	Description
width	number	Target viewport width in pixels
height	number	Target viewport height in pixels

Output	Type	Description
(side effect)	void	Adjusts the browser window rect, compensating for chrome (title bar, scrollbars) by measuring the delta between window rect and viewport, retrying up to MAX_RESIZE_RETRY_COUNT (2) times

Marionette Commands Used

Command Constant	Marionette String
newSession	WebDriver:NewSession
executeScript	WebDriver:ExecuteScript
takeScreenshot	WebDriver:TakeScreenshot
getWindowRect	WebDriver:GetWindowRect
setWindowRect	WebDriver:SetWindowRect
switchToWindow	WebDriver:SwitchToWindow
getWindowHandles	WebDriver:GetWindowHandles
getTitle	WebDriver:GetTitle
quit	Marionette:Quit

Usage Examples

// Internal usage by the Firefox browser provider:
const marionetteClient = new MarionetteClient(
    runtimeInfo.marionettePort,
    runtimeInfo
);

// Establish session with Firefox
await marionetteClient.connect();

// Execute a script in the browser
const result = await marionetteClient.executeScript(
    'function() { return document.title; }'
);

// Resize the viewport to 1024x768
await marionetteClient.setWindowSize(1024, 768);

// Take a full-page screenshot
const screenshotBuffer = await marionetteClient.getScreenshotData(true);

// Gracefully close the browser
await marionetteClient.quit();
marionetteClient.dispose();

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment