node-xvfb-ts

A TypeScript library for easily managing X Virtual Frame Buffer (Xvfb) processes in Node.js applications. Perfect for headless GUI testing with tools like Puppeteer, Playwright, or Selenium.

Installation

npm install xvfb-ts

Prerequisites

• Linux/Unix system with Xvfb installed
• Node.js >= 20.17.0

Quick Start

import { Xvfb } from 'xvfb-ts';

const xvfb = new Xvfb();

// Start the virtual display
await xvfb.start();

// Run your headless GUI tests here
// e.g., launch a browser, run Electron app, etc.

// Clean up when done
await xvfb.stop();

API Reference

Constructor Options

interface XvfbOptions {
    displayNum?: number;     // X display number (default: auto-assigned >= 99)
    reuse?: boolean;         // Reuse existing display (default: false)
    timeout?: number;        // Startup timeout in ms (default: 500)
    silent?: boolean;        // Suppress stderr output (default: false)
    xvfb_args?: string[];    // Additional Xvfb arguments (default: [])
}

Methods

• start() - Start the Xvfb process (returns Promise)
• stop() - Stop the Xvfb process (returns Promise)
• display() - Get the display string (e.g., ":99")

Examples

Basic Usage with Custom Display

import { Xvfb } from 'xvfb-ts';

const xvfb = new Xvfb({ displayNum: 88 });

await xvfb.start();

console.log(`Display: ${xvfb.display()}`); // :88

await xvfb.stop();

Reusing Existing Display

const xvfb = new Xvfb({ 
    displayNum: 99, 
    reuse: true 
});

await xvfb.start(); // Won't fail if :99 already exists

Custom Xvfb Arguments

const xvfb = new Xvfb({
    xvfb_args: ['-screen', '0', '1024x768x24']
});

await xvfb.start();

Error Handling

try {
    await xvfb.start();
    // Your code here
} catch (error) {
    console.error('Failed to start Xvfb:', error.message);
} finally {
    await xvfb.stop();
}

Credits

• Rob--W for the original node-xvfb