{"id":12658,"library":"webdriver-server","title":"Webdriver Server","description":"webdriver-server is a foundational package within the Macaca.js ecosystem, designed to provide a standalone server that implements the WebDriver protocol. As of its current stable version, 1.3.1, it enables UI automation by allowing WebDriver clients (like testing frameworks) to connect and execute commands against various browsers and mobile applications, provided the necessary drivers are configured. The project appears to be in a maintenance phase, with the last notable activity indicated by its README update in late 2022 and npm last publish 2 years ago. It serves a specific role within the broader Macaca.js framework, offering a tailored environment for Macaca-based test automation. While not a direct competitor to general-purpose, feature-rich solutions like Selenium Grid or Appium in isolation, its strength lies in its tight integration and consistent operational model within the Macaca suite, making it a suitable choice for users already invested in that platform. Its release cadence is not rapid, reflecting a stable and mature, albeit slowly evolving, component.","status":"maintenance","version":"1.3.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/macacajs/webdriver-server","tags":["javascript","webdriver","testing","ui automation","test framework"],"install":[{"cmd":"npm install webdriver-server","lang":"bash","label":"npm"},{"cmd":"yarn add webdriver-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add webdriver-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Server = require('webdriver-server');","symbol":"Server","correct":"import { Server } from 'webdriver-server';"},{"note":"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.","wrong":"import Server from 'webdriver-server'; const server = new Server(); server.start();","symbol":"start","correct":"import { start } from 'webdriver-server';"},{"note":"Used for type-checking server configuration options in TypeScript projects, assuming the package ships with type definitions.","symbol":"WebdriverServerOptions","correct":"import type { WebdriverServerOptions } from 'webdriver-server';"}],"quickstart":{"code":"import { Server } from 'webdriver-server';\nimport path from 'path';\n\n// Ensure necessary browser drivers (e.g., chromedriver, geckodriver)\n// are available in your system's PATH or explicitly configured.\n// For example, you might install them globally or manage them with a tool like `webdriver-manager`.\n\nasync function startWebdriverServer() {\n  const options = {\n    port: 4444,\n    host: 'localhost',\n    logLevel: 'info', // Can be 'info', 'warn', 'error', 'debug'\n    // Additional options for driver paths, capabilities, etc., would be configured here\n    // based on the specific WebDriver client (e.g., Macaca, Selenium, Appium).\n    // Example (if server directly manages drivers, which is not typical for a generic server):\n    // chromeDriverPath: '/usr/local/bin/chromedriver',\n  };\n\n  try {\n    const server = new Server(options); // Instantiate the WebDriver server\n    await server.start(); // Start the server, making it listen for connections\n    console.log(`WebDriver Server started successfully on http://${options.host}:${options.port}`);\n    console.log('Press Ctrl+C to stop the server.');\n\n    // Keep the process alive indefinitely, typically for a CI/CD environment or background service\n    process.on('SIGINT', async () => {\n      console.log('\\nShutting down WebDriver Server...');\n      await server.stop(); // Assuming a .stop() method exists for graceful shutdown\n      process.exit(0);\n    });\n    process.on('SIGTERM', async () => {\n      console.log('\\nShutting down WebDriver Server...');\n      await server.stop();\n      process.exit(0);\n    });\n\n  } catch (error: any) {\n    console.error('Failed to start WebDriver Server:', error.message);\n    process.exit(1);\n  }\n}\n\nstartWebdriverServer();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the `port` option in your server configuration to an unused port, or terminate the process currently occupying the port.","cause":"The specified port (e.g., 4444) is already being used by another application or another instance of webdriver-server.","error":"Error: listen EADDRINUSE: address already in use :::4444"},{"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).","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.","error":"WebDriverError: A session is either terminated or not started"},{"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.","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.","error":"Error: No driver found for the requested capabilities."}],"ecosystem":"npm"}