@wdio/xvfb
Advanced tools
A standalone utility to manage Xvfb (X Virtual Framebuffer) for headless testing
A standalone utility to manage Xvfb (X Virtual Framebuffer) for headless testing on Linux systems.
npm install @wdio/xvfb
Most users don't need to use this package directly. It's automatically integrated into:
@wdio/local-runner - Automatically ensures xvfb is available for headless browser testing@wdio/electron-service - Provides headless Electron testing capabilitiesSimply run your WebDriverIO tests normally, and xvfb will be managed automatically when needed.
For custom integrations or non-WDIO environments:
import { xvfb } from "@wdio/xvfb";
// Initialize xvfb-run (only works on Linux in headless environments)
const ready = await xvfb.init();
if (ready) {
console.log("xvfb-run is ready for use");
// Use xvfb-run to execute commands that need a display
// e.g., xvfb-run npm test
}
interface XvfbOptions {
enabled?: boolean; // Authoritative usage toggle (default: true). If false, never uses Xvfb
force?: boolean; // Force Xvfb even on non-Linux systems (for testing)
autoInstall?: boolean; // Enable automatic installation of xvfb-run if missing (default: false)
autoInstallMode?: 'root' | 'sudo'; // Installation mode when autoInstall is true (default: 'sudo')
autoInstallCommand?: string | string[]; // Custom installation command (overrides built-in package manager detection)
xvfbMaxRetries?: number; // Number of retry attempts for xvfb failures (default: 3)
xvfbRetryDelay?: number; // Base delay between retries in milliseconds (default: 1000)
}
shouldRun(capabilities?): boolean - Check if Xvfb should run on this systeminit(capabilities?): Promise<boolean> - Initialize xvfb-run, returns true if ready, false if not neededexecuteWithRetry<T>(commandFn, context?): Promise<T> - Execute a function with automatic retry on xvfb-related errorsFor testing on non-Linux systems:
import { XvfbManager } from "@wdio/xvfb";
const manager = new XvfbManager({
force: true,
xvfbMaxRetries: 3,
xvfbRetryDelay: 1000
});
const ready = await manager.init();
import { XvfbManager } from "@wdio/xvfb";
// High-reliability setup for CI environments
const manager = new XvfbManager({
xvfbMaxRetries: 10, // More retries for flaky CI
xvfbRetryDelay: 500 // Faster retries
});
// Execute operation with automatic retry
const result = await manager.executeWithRetry(async () => {
// Your operation that might fail due to xvfb issues
return await runHeadlessTests();
}, 'Running headless tests');
The utility automatically detects when Xvfb is needed:
--headless, --headless=new, --headless=old--headless, -headless--headless, --headless=new, --headless=oldforce: true)--headless, --headless=new, etc.) and forces XVFB usage for consistent behaviorapt, dnf, yum, zypper, pacman, apk, xbps)xvfb-runThe package includes automatic retry functionality for handling xvfb-related failures:
The retry mechanism automatically detects xvfb-specific errors:
xvfb-run: error: Xvfb failed to startXvfb failed to startxvfb-run: error:X server diedRetry delays increase progressively to avoid overwhelming the system:
xvfbRetryDelay × 1 ms (default: 1000ms)xvfbRetryDelay × 2 ms (default: 2000ms)xvfbRetryDelay × (N-1) msimport { XvfbManager } from '@wdio/xvfb';
const manager = new XvfbManager({
xvfbMaxRetries: 5,
xvfbRetryDelay: 1500
});
// Automatic retry on xvfb failures
const result = await manager.executeWithRetry(async () => {
// Your xvfb-dependent operation
return await someXvfbDependentTask();
}, 'Custom operation name');
This package uses xvfb-run to manage Xvfb sessions, which:
--auto-servernumThe utility automatically detects the system's package manager and installs xvfb accordingly:
| Package Manager | Command | Distributions | Package Name |
|---|---|---|---|
apt | apt-get | Ubuntu, Debian, Pop!_OS, Mint, Elementary, Zorin, etc. | xvfb |
dnf | dnf | Fedora, Rocky Linux, AlmaLinux, Nobara, Bazzite, etc. | xorg-x11-server-Xvfb |
yum | yum | CentOS, RHEL (legacy) | xorg-x11-server-Xvfb |
zypper | zypper | openSUSE, SUSE Linux Enterprise | xvfb-run |
pacman | pacman | Arch Linux, Manjaro, EndeavourOS, CachyOS, etc. | xorg-server-xvfb |
apk | apk | Alpine Linux, PostmarketOS | xvfb-run |
xbps | xbps-install | Void Linux | xvfb |
This package manager-focused approach means new Linux distributions automatically work without code changes, as long as they use one of the supported package managers. For example:
aptpacmandnfThe 7 supported package managers cover 95%+ of all Linux users and hundreds of distributions, making this solution both comprehensive and maintainable.
import { xvfb } from "@wdio/xvfb";
import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);
async function runCustomTests() {
const ready = await xvfb.init();
const command = ready
? "xvfb-run your-custom-test-command"
: "your-custom-test-command";
await execAsync(command);
}
For most users, no configuration is needed. WDIO automatically handles xvfb:
// wdio.conf.js - Minimal configuration
export const config = {
// No xvfb configuration needed - handled automatically
capabilities: [{
browserName: 'chrome',
'goog:chromeOptions': {
args: ['--headless', '--no-sandbox'] // Automatically detected - will force XVFB
}
}],
services: [
'chromedriver',
// xvfb is automatically managed by local-runner
]
};
You can customize xvfb behavior and retry settings in your WDIO config file:
// wdio.conf.js - Custom xvfb configuration
export const config = {
// Xvfb configuration options (all optional)
autoXvfb: true, // Authoritative usage toggle (default: true). If false, never uses Xvfb
xvfbAutoInstall: false, // Enable automatic installation of xvfb-run if missing (default: false)
xvfbAutoInstallMode: 'sudo', // Installation mode: 'root' or 'sudo' (default: 'sudo')
xvfbAutoInstallCommand: undefined, // Custom installation command (optional)
xvfbMaxRetries: 5, // Max retry attempts for xvfb failures (default: 3)
xvfbRetryDelay: 2000, // Base delay between retries in ms (default: 1000)
capabilities: [{
browserName: 'chrome',
'goog:chromeOptions': {
args: ['--headless', '--no-sandbox']
}
}]
};
WDIO Testrunner Configuration Options:
autoXvfb (boolean, default: true): Authoritative usage toggle – if false, Xvfb is never usedxvfbAutoInstall (boolean, default: false): Enable automatic installation when xvfb-run is missingxvfbAutoInstallMode ('root' | 'sudo', default: 'sudo'): Installation mode
sudo -n) when not root; skip if sudo not presentxvfbAutoInstallCommand (string | string[], optional): Custom installation command that overrides built-in package manager detectionxvfbMaxRetries (number, default: 3): Number of retry attempts when xvfb process failsxvfbRetryDelay (number, default: 1000): Base delay between retries in milliseconds. Uses progressive delay (delay × attempt number)The utility automatically detects browser headless flags and forces XVFB usage even when a DISPLAY is available:
// These configurations will automatically trigger XVFB on Linux:
// Chrome/Chromium
capabilities: [{
'goog:chromeOptions': {
args: ['--headless'] // Detected
}
}]
// Firefox
capabilities: [{
'moz:firefoxOptions': {
args: ['--headless'] // Detected
}
}]
// Edge (Chromium-based)
capabilities: [{
'ms:edgeOptions': {
args: ['--headless=new'] // Detected
}
}]
// Legacy formats also supported
capabilities: [{
chromeOptions: { args: ['--headless'] }, // Legacy Chrome
edgeOptions: { args: ['--headless'] } // Legacy Edge
}]
// Multiremote scenarios are also supported
capabilities: {
browserA: { 'goog:chromeOptions': { args: ['--headless'] }},
browserB: { 'ms:edgeOptions': { args: ['--no-sandbox'] }}
// XVFB will be used because browserA has headless flag
}
This ensures consistent headless behavior regardless of host environment setup.
The utility uses @wdio/logger with the namespace @wdio/xvfb. Enable debug logging:
DEBUG=@wdio/xvfb npm run test
The logger is automatically created with the namespace @wdio/xvfb and cannot be customized in the current interface.
MIT
The 'xvfb' package provides a similar functionality by allowing you to run Xvfb from Node.js. It is a more general-purpose package compared to @wdio/xvfb, which is specifically designed to integrate with WebdriverIO.
The 'headless-gl' package provides a WebGL context without a display, similar to how Xvfb provides a virtual framebuffer. While it is more focused on WebGL rendering, it can be used in similar headless testing scenarios.
FAQs
A standalone utility to manage Xvfb (X Virtual Framebuffer) for headless testing
The npm package @wdio/xvfb receives a total of 335,068 weekly downloads. As such, @wdio/xvfb popularity was classified as popular.
We found that @wdio/xvfb demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.