0
# Selenium Standalone
1

2
Selenium Standalone is a Node.js CLI tool and library for installing and starting standalone Selenium servers with WebDriver support. It automatically downloads and manages Selenium server JARs and browser drivers (Chrome, Firefox, Internet Explorer, Edge, and Chromium Edge), providing both programmatic APIs and command-line interfaces for web automation testing workflows.
3

4
## Package Information
5

6
- **Package Name**: selenium-standalone
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install selenium-standalone` (local) or `npm install selenium-standalone -g` (global)
10

11
## Core Imports
12

13
```javascript
14
const selenium = require('selenium-standalone');
15
```
16

17
For ES modules:
18

19
```javascript
20
import selenium from 'selenium-standalone';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const selenium = require('selenium-standalone');
27

28
async function setupSelenium() {
29
  // Install Selenium server and drivers
30
  await selenium.install({
31
    version: '4.10.0',
32
    drivers: {
33
      chrome: {
34
        version: 'latest',
35
        arch: process.arch
36
      },
37
      firefox: {
38
        version: 'latest',
39
        arch: process.arch
40
      }
41
    }
42
  });
43

44
  // Start Selenium server
45
  const seleniumProcess = await selenium.start({
46
    drivers: {
47
      chrome: {
48
        version: 'latest'
49
      },
50
      firefox: {
51
        version: 'latest'
52
      }
53
    }
54
  });
55

56
  // Use seleniumProcess for WebDriver connections...
57
  
58
  // Clean up when done
59
  seleniumProcess.kill();
60
}
61
```
62

63
## Architecture
64

65
Selenium Standalone consists of several key components:
66

67
- **Installation API**: Downloads and manages Selenium server JARs and browser drivers with version control and proxy support
68
- **Server Management**: Starts and configures Selenium standalone servers with Java process management
69
- **Driver Support**: Handles ChromeDriver, geckodriver (Firefox), IEDriver, Edge WebDriver, and Chromium Edge WebDriver
70
- **CLI Interface**: Command-line tools for installation and server management with progress indicators
71
- **Configuration System**: Flexible configuration through options objects, config files, and environment variables
72
- **Process Management**: Automatic port conflict resolution and process cleanup utilities
73

74
## Capabilities
75

76
### Installation
77

78
Downloads and installs Selenium server and browser drivers with comprehensive configuration options including version control, proxy support, and progress reporting.
79

80
```javascript { .api }
81
/**
82
 * Downloads and installs Selenium server and browser drivers
83
 * @param opts - Installation configuration options
84
 * @returns Promise<InstallResult> Installation details with file paths and URLs
85
 */
86
function install(opts?: InstallOptions): Promise<InstallResult>;
87

88
interface InstallOptions {
89
  /** Base directory for storing selenium files. Defaults to node_modules/selenium-standalone/.selenium */
90
  basePath?: string;
91
  /** Base URL for selenium server downloads. Defaults to GitHub releases */
92
  baseURL?: string;
93
  /** Map of drivers to download and install */
94
  drivers?: Drivers;
95
  /** Complete URL for selenium server jar as alternative to baseURL */
96
  fullURL?: string;
97
  /** Only downloads drivers explicitly specified when true */
98
  ignoreExtraDrivers?: boolean;
99
  /** Logging function for installation progress */
100
  logger?: Logger;
101
  /** Install only specific driver without selenium server */
102
  onlyDriver?: keyof Drivers;
103
  /** Progress callback for download progress reporting */
104
  progressCb?: ProgressCallback;
105
  /** HTTP request options for downloads (proxy, timeout, etc.) */
106
  requestOpts?: RequestOptions;
107
  /** Single driver installation mode */
108
  singleDriverInstall?: keyof Drivers;
109
  /** Selenium server version to install */
110
  version?: string;
111
}
112

113
interface InstallResult {
114
  /** File system paths for installed components */
115
  fsPaths: Record<string, PathInfo>;
116
  /** Download URLs used for installation */
117
  urls: Record<string, string>;
118
  /** Processed options used for installation */
119
  opts: InstallOptions;
120
}
121

122
interface PathInfo {
123
  /** Path where component is installed */
124
  installPath: string;
125
  /** Path where component was downloaded */
126
  downloadPath: string;
127
  /** Whether component requires executable permissions */
128
  requireChmod?: boolean;
129
}
130
```
131

132
### Server Management
133

134
Starts Selenium standalone servers or individual browser drivers with Java process management, port conflict resolution, and comprehensive configuration options.
135

136
```javascript { .api }
137
/**
138
 * Starts Selenium server or individual browser drivers
139
 * @param opts - Start configuration options
140
 * @returns Promise<ChildProcess> The running selenium or driver process
141
 */
142
function start(opts?: StartOptions): Promise<ChildProcess>;
143

144
interface StartOptions {
145
  /** Base directory for selenium files */
146
  basePath?: string;
147
  /** Map of drivers to start along with selenium server */
148
  drivers?: Drivers;
149
  /** Array of arguments for the JVM */
150
  javaArgs?: string | readonly string[];
151
  /** Path to Java executable. Auto-detected if not provided */
152
  javaPath?: string;
153
  /** Start only specific driver without selenium server */
154
  onlyDriver?: keyof Drivers;
155
  /** Disable automatic port killing when false */
156
  processKiller?: boolean;
157
  /** Array of arguments for selenium server */
158
  seleniumArgs?: string[];
159
  /** Single driver start mode */
160
  singleDriverStart?: keyof Drivers;
161
  /** Spawn options for child process */
162
  spawnOptions?: SpawnOptions;
163
  /** Selenium server version to start */
164
  version?: string;
165
}
166
```
167

168
### Command Line Interface
169

170
Provides `selenium-standalone` command with install and start subcommands, supporting configuration files and comprehensive options.
171

172
**Installation Command:**
173
```bash
174
selenium-standalone install [options]
175
```
176

177
**Start Command:**
178
```bash
179
selenium-standalone start [options]
180
```
181

182
**Global Options:**
183
- `--version <version>` - Selenium server version
184
- `--drivers.chrome.version <version>` - Chrome driver version
185
- `--drivers.firefox.version <version>` - Firefox driver version  
186
- `--drivers.ie.version <version>` - Internet Explorer driver version (Windows only)
187
- `--drivers.edge.version <version>` - Edge driver version (Windows only)
188
- `--config <path>` - Configuration file path
189
- `--silent` - Suppress progress output
190
- Additional options for proxy, base path, and driver-specific settings
191

192
## Types
193

194
```javascript { .api }
195
/** Configuration for browser drivers */
196
interface Drivers {
197
  chrome?: DriverConfig;
198
  firefox?: DriverConfig;
199
  chromiumedge?: DriverConfig;
200
  ie?: DriverConfig;
201
  edge?: DriverConfig;
202
}
203

204
interface DriverConfig {
205
  /** Driver version (supports 'latest') */
206
  version: string;
207
  /** Fallback version if latest detection fails */
208
  fallbackVersion?: string;
209
  /** Chrome channel for Chrome driver (stable, beta, dev) */
210
  channel?: string;
211
  /** Architecture (ia32, x64, arm64) */
212
  arch: NodeJS.Architecture;
213
  /** Arguments for driver when started alone */
214
  onlyDriverArgs: string[];
215
  /** Base URL for driver downloads */
216
  baseURL: string;
217
}
218

219
/** Logging function type */
220
interface Logger {
221
  (...args: any[]): void;
222
}
223

224
/** Progress callback for downloads */
225
interface ProgressCallback {
226
  (total: number, progress: number | undefined, chunk: any, url: string, reset: any): void;
227
}
228

229
/** HTTP request configuration */
230
interface RequestOptions {
231
  /** Request timeout in milliseconds */
232
  timeout?: number;
233
  /** HTTP proxy agent */
234
  agent?: any;
235
  /** Additional got options */
236
  [key: string]: any;
237
}
238

239
/** Child process spawn options */
240
interface SpawnOptions {
241
  /** Standard I/O configuration */
242
  stdio?: string | Array<string>;
243
  /** Working directory */
244
  cwd?: string;
245
  /** Environment variables */
246
  env?: Record<string, string>;
247
  /** Additional spawn options */
248
  [key: string]: any;
249
}
250
```
251

252
## Default Configuration
253

254
```javascript { .api }
255
/** Default configuration values */
256
interface DefaultConfig {
257
  /** Default Selenium server download URL */
258
  baseURL: 'https://github.com/SeleniumHQ/selenium/releases/download';
259
  /** Default Selenium version (4.10.0 or SELENIUM_VERSION env var) */
260
  version: string;
261
  /** Default driver configurations (IE and Edge drivers not included, require user configuration) */
262
  drivers: {
263
    chrome: {
264
      version: 'latest';
265
      channel: 'stable';
266
      arch: NodeJS.Architecture; // process.arch
267
      onlyDriverArgs: [];
268
      baseURL: 'https://storage.googleapis.com/chrome-for-testing-public';
269
    };
270
    firefox: {
271
      version: 'latest';
272
      fallbackVersion: '0.30.0';
273
      arch: NodeJS.Architecture; // process.arch
274
      onlyDriverArgs: [];
275
      baseURL: 'https://github.com/mozilla/geckodriver/releases/download';
276
    };
277
    chromiumedge: {
278
      version: 'latest';
279
      fallbackVersion: '117.0.2045.55';
280
      arch: NodeJS.Architecture; // process.arch
281
      onlyDriverArgs: [];
282
      baseURL: 'https://msedgedriver.microsoft.com';
283
    };
284
  };
285
}
286
```
287

288
**Note**: Internet Explorer and Edge (legacy) drivers are supported but not included in the default configuration. They are Windows-only and require explicit configuration including version and baseURL when used.
289

290
## Environment Variables
291

292
```javascript { .api }
293
/** Supported environment variables */
294
interface EnvironmentVariables {
295
  /** Override default Selenium version */
296
  SELENIUM_VERSION?: string;
297
  /** HTTP proxy for downloads */
298
  HTTP_PROXY?: string;
299
  /** HTTPS proxy for downloads */
300
  HTTPS_PROXY?: string;
301
  /** Environment mode (affects CLI testing behavior) */
302
  NODE_ENV?: string;
303
}
304
```
305

306
## Supported Platforms
307

308
- **Chrome/Chromium**: All platforms via ChromeDriver
309
- **Firefox**: All platforms via geckodriver  
310
- **Internet Explorer**: Windows only via IEDriver
311
- **Edge (Legacy)**: Windows only via Edge WebDriver
312
- **Chromium Edge**: All platforms via EdgeDriver
313
- **Safari**: macOS only (driver bundled with Safari, Selenium 4+ only)
314

315
## Usage Examples
316

317
**Custom Configuration:**
318
```javascript
319
const selenium = require('selenium-standalone');
320

321
// Install with custom configuration
322
await selenium.install({
323
  version: '4.10.0',
324
  baseURL: 'https://selenium-release.storage.googleapis.com',
325
  drivers: {
326
    chrome: {
327
      version: '114.0.5735.90',
328
      arch: 'x64',
329
      baseURL: 'https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing'
330
    }
331
  },
332
  requestOpts: {
333
    timeout: 60000
334
  }
335
});
336
```
337

338
**Driver-Only Mode:**
339
```javascript
340
// Install and start only Chrome driver
341
await selenium.install({
342
  onlyDriver: 'chrome',
343
  drivers: {
344
    chrome: { version: 'latest' }
345
  }
346
});
347

348
const chromeDriver = await selenium.start({
349
  onlyDriver: 'chrome',
350
  drivers: {
351
    chrome: {
352
      version: 'latest',
353
      onlyDriverArgs: ['--port=9515', '--whitelisted-ips=']
354
    }
355
  }
356
});
357
```
358

359
**Configuration File:**
360
```javascript
361
// config.js
362
module.exports = {
363
  version: '4.10.0',
364
  drivers: {
365
    chrome: { version: 'latest' },
366
    firefox: { version: '0.30.0' }
367
  }
368
};
369

370
// Usage with config file
371
// selenium-standalone install --config ./config.js
372
```
373

374
**Proxy Configuration:**
375
```javascript
376
await selenium.install({
377
  requestOpts: {
378
    agent: {
379
      https: new HttpsProxyAgent('http://proxy-server:8080')
380
    }
381
  }
382
});
383
```