Overview
BrowserProviderPluginHost is the base class that wraps browser provider plugin objects, supplying shared helper methods and defining the contract that all browser providers (built-in and third-party) must implement.
Description
The BrowserProviderPluginHost class in src/browser/provider/plugin-host.js serves as the host wrapper for browser provider plugins. It accepts a raw provider object and a provider name, then merges (via lodash.assignIn) the provider's methods onto itself so they become first-class members. The class provides shared infrastructure methods -- runInitScript, waitForConnectionReady, reportWarning, setUserAgentMetaInfo, closeLocalBrowser, resizeLocalBrowserWindow, and calculateWindowId -- that delegate to BrowserConnection instances looked up by browserId. It also defines the full API surface with sensible defaults: openBrowser and closeBrowser throw "Not implemented!" errors to enforce overriding; resizeWindow, takeScreenshot, and maximizeWindow issue warning messages; and capability queries like hasCustomActionForBrowser auto-detect overrides via hasOwnProperty checks. The JOB_RESULT property exposes the BROWSER_JOB_RESULT enum for reporting test outcomes.
Usage
Every browser provider in TestCafe (chrome, firefox, edge, safari, and third-party npm plugins) is wrapped in a BrowserProviderPluginHost when registered. The class is instantiated by the browser provider pool during initialization. Plugin authors who create custom browser providers (e.g., testcafe-browser-provider-xxx) have their exported object merged into this host, gaining access to the helper methods automatically.
Code Reference
Source Location
Signature
export default class BrowserProviderPluginHost {
constructor (providerObject, providerName)
// Properties
JOB_RESULT: object // copy of BROWSER_JOB_RESULT enum
// Getter
get providerName (): string
// Helper methods
async runInitScript (browserId, code): Promise<any>
calculateWindowId (): string
waitForConnectionReady (browserId): Promise<void>
reportWarning (browserId, ...args): void
setUserAgentMetaInfo (browserId, message, ...args): void
async closeLocalBrowser (browserId): Promise<void>
async resizeLocalBrowserWindow (browserId, width, height, currentWidth, currentHeight): Promise<void>
// API - Browser control (must override)
async openBrowser (/* browserId, pageUrl, browserName */): Promise<void>
async closeBrowser (/* browserId */): Promise<void>
// API - Initialization
async init (): Promise<void>
async dispose (): Promise<void>
// API - Browser names handling
async getBrowserList (): Promise<string[]>
async isValidBrowserName (/* browserName */): Promise<boolean>
// API - Extra functions
async isLocalBrowser (/* browserId[, browserName] */): Promise<boolean>
isHeadlessBrowser (/* browserId[, browserName] */): boolean
async hasCustomActionForBrowser (/* browserId */): Promise<object>
async resizeWindow (browserId /*, width, height, currentWidth, currentHeight */): Promise<void>
async canResizeWindowToDimensions (/* browserId, width, height */): Promise<boolean>
async takeScreenshot (browserId /*, screenshotPath, pageWidth, pageHeight */): Promise<void>
async maximizeWindow (browserId): Promise<void>
async startCapturingVideo (/* browserId */): Promise<void>
async stopCapturingVideo (/* browserId */): Promise<void>
async getVideoFrameData (browserId): Promise<void>
async reportJobResult (/* browserId, status, data */): Promise<void>
getConfig (value): any
async closeBrowserChildWindow (/* browserId, windowId */): Promise<void>
async getOSInfo (/* browserId */): Promise<null>
supportNativeAutomation (): boolean
getNativeAutomation (/* browserId */): null
getNewWindowIdInNativeAutomation (/* browserId, windowId */): Promise<void>
async getCurrentCDPSession (/* browserId */): Promise<void>
}
Import
import BrowserProviderPluginHost from '../browser/provider/plugin-host';
I/O Contract
Constructor
| Input |
Type |
Description
|
| providerObject |
object |
The raw browser provider plugin (an object literal or class instance) whose methods are merged onto the host
|
| providerName |
string |
The registered name of the provider (e.g., chrome, firefox, browserstack)
|
| Output |
Type |
Description
|
| instance |
BrowserProviderPluginHost |
A host object that contains both the plugin's methods and the shared helpers
|
hasCustomActionForBrowser(browserId)
| Output Key |
Type |
Default |
Description
|
| hasCloseBrowser |
boolean |
hasOwnProperty check |
Whether the provider overrides closeBrowser
|
| hasResizeWindow |
boolean |
hasOwnProperty check |
Whether the provider overrides resizeWindow
|
| hasTakeScreenshot |
boolean |
hasOwnProperty check |
Whether the provider overrides takeScreenshot
|
| hasGetVideoFrameData |
boolean |
hasOwnProperty check |
Whether the provider overrides getVideoFrameData
|
| hasCanResizeWindowToDimensions |
boolean |
hasOwnProperty check |
Whether the provider overrides canResizeWindowToDimensions
|
| hasMaximizeWindow |
boolean |
hasOwnProperty check |
Whether the provider overrides maximizeWindow
|
| hasChromelessScreenshots |
boolean |
false |
Always false in the base; Chrome provider overrides this
|
Usage Examples
// Internal: how TestCafe wraps a provider plugin
import BrowserProviderPluginHost from '../browser/provider/plugin-host';
const chromeProviderObject = {
async openBrowser (browserId, pageUrl, config, additionalOptions) {
// Chrome-specific launch logic
},
async closeBrowser (browserId) {
// Chrome-specific close logic
},
};
const host = new BrowserProviderPluginHost(chromeProviderObject, 'chrome');
// The host now has both custom and inherited methods:
console.log(host.providerName); // 'chrome'
await host.waitForConnectionReady(browserId);
await host.openBrowser(browserId, pageUrl, config, options);
// Custom third-party browser provider plugin pattern:
// File: testcafe-browser-provider-my-cloud/index.js
export default {
async openBrowser (browserId, pageUrl, browserName) {
// Launch browser on cloud service
},
async closeBrowser (browserId) {
// Terminate cloud browser
},
async getBrowserList () {
return ['chrome@latest', 'firefox@latest'];
},
async isValidBrowserName (browserName) {
const list = await this.getBrowserList();
return list.includes(browserName);
},
};
// TestCafe wraps this in BrowserProviderPluginHost automatically,
// giving it access to runInitScript, waitForConnectionReady, etc.
Related Pages
