Webdriver Server

Common errors

• Error: listen EADDRINUSE: address already in use :::4444

  cause The specified port (e.g., 4444) is already being used by another application or another instance of webdriver-server.
  fix Change the `port` option in your server configuration to an unused port, or terminate the process currently occupying the port.

• WebDriverError: A session is either terminated or not started

  cause The WebDriver client attempted to interact with a session that either doesn't exist, has already been closed, or failed to initialize correctly on the server side.
  fix Ensure the client correctly establishes a new session before sending commands. Check server logs for errors during session creation (e.g., driver not found, capabilities mismatch).

• Error: No driver found for the requested capabilities.

  cause The `webdriver-server` could not find the necessary browser driver (e.g., `chromedriver`, `geckodriver`) to fulfill the desired capabilities specified by the client. This typically means the driver is not installed or not in the system's PATH.
  fix Install the required browser driver(s) (e.g., `npm install -g chromedriver`). Verify the driver executable is available in your system's PATH environment variable. If applicable, explicitly configure the driver path in the `webdriver-server` options.

Warnings

• gotcha The WebDriver protocol is continuously evolving. While `webdriver-server` aims for compliance, significant updates to the W3C WebDriver specification or browser driver implementations (e.g., ChromeDriver, GeckoDriver) may require updates to `webdriver-server` or its dependencies.
  Fix: Regularly check the `webdriver-server` GitHub repository for updates and review release notes for compatibility with newer browser versions or WebDriver protocol changes. Ensure your browser drivers are up-to-date.
• gotcha Like any network service, `webdriver-server` requires an available port. Attempting to start the server on a port already in use will result in an `EADDRINUSE` error.
  Fix: Specify an alternative port in the server configuration (e.g., `port: 4445`) or ensure no other process is listening on the desired port. You can use tools like `lsof -i :<port>` (macOS/Linux) or `netstat -ano | findstr :<port>` (Windows) to identify processes using a port.
• gotcha `webdriver-server` itself provides the WebDriver protocol endpoint but typically relies on external browser-specific drivers (like ChromeDriver for Chrome or GeckoDriver for Firefox) to interact with actual browsers. These drivers must be installed and accessible in the system's PATH, or their paths must be explicitly configured.
  Fix: Install the necessary browser drivers for your target browsers (e.g., via `npm install -g chromedriver` or `webdriver-manager update`). Verify they are accessible in your system's PATH. For a more robust setup, consider a WebDriver manager solution or explicitly pass driver paths if the server supports it.
• gotcha As `webdriver-server` is specifically part of the Macaca.js ecosystem, its standalone features might be less extensive or actively developed compared to dedicated, general-purpose WebDriver servers (e.g., Selenium Grid Standalone or Appium). Its primary design intent is often to integrate within Macaca's broader automation solutions.
  Fix: If integrating with Macaca.js, follow their recommended setup for `webdriver-server`. For non-Macaca use cases, thoroughly evaluate if it meets your requirements compared to alternatives, and be prepared for potentially less community support for generic standalone usage.

Install

• npm install webdriver-server npm
• yarn add webdriver-server yarn
• pnpm add webdriver-server pnpm

Imports

• Server
  wrong:

  const Server = require('webdriver-server');

  correct:

  import { Server } from 'webdriver-server';

  CommonJS import style for the Server class might require a default import or accessing a property if not explicitly exported as named. ESM is preferred for modern Node.js applications.
• start
  wrong:

  import Server from 'webdriver-server'; const server = new Server(); server.start();

  correct:

  import { start } from 'webdriver-server';

  Some server packages export a direct 'start' function for convenience instead of requiring class instantiation. The exact export depends on the package's internal structure.
• WebdriverServerOptions

  import type { WebdriverServerOptions } from 'webdriver-server';

  Used for type-checking server configuration options in TypeScript projects, assuming the package ships with type definitions.

Quickstart

This quickstart demonstrates how to instantiate and start the `webdriver-server` using its `Server` class, listening on a specified port. It includes basic error handling and graceful shutdown logic.

import { Server } from 'webdriver-server';
import path from 'path';

// Ensure necessary browser drivers (e.g., chromedriver, geckodriver)
// are available in your system's PATH or explicitly configured.
// For example, you might install them globally or manage them with a tool like `webdriver-manager`.

async function startWebdriverServer() {
  const options = {
    port: 4444,
    host: 'localhost',
    logLevel: 'info', // Can be 'info', 'warn', 'error', 'debug'
    // Additional options for driver paths, capabilities, etc., would be configured here
    // based on the specific WebDriver client (e.g., Macaca, Selenium, Appium).
    // Example (if server directly manages drivers, which is not typical for a generic server):
    // chromeDriverPath: '/usr/local/bin/chromedriver',
  };

  try {
    const server = new Server(options); // Instantiate the WebDriver server
    await server.start(); // Start the server, making it listen for connections
    console.log(`WebDriver Server started successfully on http://${options.host}:${options.port}`);
    console.log('Press Ctrl+C to stop the server.');

    // Keep the process alive indefinitely, typically for a CI/CD environment or background service
    process.on('SIGINT', async () => {
      console.log('\nShutting down WebDriver Server...');
      await server.stop(); // Assuming a .stop() method exists for graceful shutdown
      process.exit(0);
    });
    process.on('SIGTERM', async () => {
      console.log('\nShutting down WebDriver Server...');
      await server.stop();
      process.exit(0);
    });

  } catch (error: any) {
    console.error('Failed to start WebDriver Server:', error.message);
    process.exit(1);
  }
}

startWebdriverServer();