Registry / testing / webdriver-server

webdriver-server

JSON →
library1.3.1jsnpmunverified

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.

npm install webdriver-server
INSTALL
IMPORT
SIG · WEBDRIVER-SERVER
W
webdriver-server
testingjavascriptv1.3.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server
✓ import { Server } from 'webdriver-server';
✗ const Server = require('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
✓ import { start } from 'webdriver-server';
✗ import Server from 'webdriver-server'; const server = new Server(); server.start();
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.

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();
Debug
Known issues
gotchaThe 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.
affects: >=1.0.0
gotchaLike 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.
affects: >=1.0.0
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.
affects: >=1.0.0
gotchaAs `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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: listen EADDRINUSE: address already in use :::4444
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
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.
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.
Upgrade
Version history
1.3.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
18
OpenAI (training)
1
Resources
webdriver-server — npm install webdriver-server · libregistry