0
# WebdriverIO Selenium Standalone Service
1

2
A WebdriverIO service that automates the management of Selenium Standalone server during test execution. This service simplifies test setup by automatically handling the installation, configuration, and lifecycle of the Selenium server and browser drivers without requiring separate driver services.
3

4
## Package Information
5

6
- **Package Name**: @wdio/selenium-standalone-service
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @wdio/selenium-standalone-service --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import SeleniumStandaloneService, { launcher } from "@wdio/selenium-standalone-service";
15
import type { SeleniumStandaloneOptions } from "@wdio/selenium-standalone-service";
16
import { getFilePath, hasCapsWithSupportedBrowser } from "@wdio/selenium-standalone-service";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const SeleniumStandaloneService = require("@wdio/selenium-standalone-service").default;
23
const { launcher, getFilePath, hasCapsWithSupportedBrowser } = require("@wdio/selenium-standalone-service");
24
```
25

26
## Basic Usage
27

28
```typescript
29
// WebdriverIO configuration (wdio.conf.js)
30
export const config = {
31
  // ... other config
32
  outputDir: "./logs", // Logs will be written here
33
  services: [
34
    ["selenium-standalone", {
35
      drivers: {
36
        chrome: true,
37
        firefox: "0.33.0"
38
      }
39
    }]
40
  ],
41
  capabilities: [{
42
    browserName: "chrome"
43
  }]
44
};
45
```
46

47
## Architecture
48

49
The service provides automated Selenium server lifecycle management through:
50

51
- **Service Class**: Empty `SeleniumStandaloneService` class for WebdriverIO compatibility
52
- **Launcher Implementation**: `SeleniumStandaloneLauncher` handles server installation, startup, and teardown
53
- **Configuration Modes**: Simplified driver configuration and advanced selenium-standalone integration
54
- **Capability Integration**: Automatic capability configuration for local Selenium connection
55
- **Lifecycle Management**: Integration with WebdriverIO's onPrepare/onComplete hooks
56

57
## Capabilities
58

59
### Service Configuration
60

61
Main service class exported as default for WebdriverIO service integration.
62

63
```typescript { .api }
64
/**
65
 * WebdriverIO service class for Selenium Standalone integration
66
 */
67
export default class SeleniumStandaloneService {}
68

69
/**
70
 * Launcher class for handling Selenium server lifecycle
71
 */
72
export const launcher: typeof SeleniumStandaloneLauncher;
73

74
/**
75
 * All types and interfaces from the types module
76
 */
77
export * from './types';
78
```
79

80
### Selenium Server Management
81

82
Core launcher class that manages Selenium server installation, startup, and teardown.
83

84
```typescript { .api }
85
/**
86
 * Launcher class for managing Selenium Standalone server lifecycle
87
 */
88
class SeleniumStandaloneLauncher {
89
  constructor(
90
    options: SeleniumStandaloneOptions,
91
    capabilities: Capabilities.RemoteCapabilities,
92
    config: Omit<Options.Testrunner, 'capabilities'>
93
  );
94

95
  /**
96
   * Lifecycle hook called before test execution starts
97
   * Installs drivers, starts Selenium server, configures capabilities
98
   */
99
  async onPrepare(config: Options.Testrunner): Promise<void>;
100

101
  /**
102
   * Lifecycle hook called after test execution completes
103
   * Stops the Selenium server process
104
   */
105
  onComplete(): void;
106

107
  /** Selenium start arguments */
108
  args: SeleniumStartArgs;
109
  
110
  /** Selenium install arguments */
111
  installArgs: SeleniumInstallArgs;
112
  
113
  /** Whether to skip selenium installation */
114
  skipSeleniumInstall: boolean;
115
  
116
  /** Watch mode flag */
117
  watchMode: boolean;
118
  
119
  /** Running Selenium process reference */
120
  process: SeleniumStandalone.ChildProcess;
121
  
122
  /** Browser driver versions for simplified mode */
123
  drivers?: {
124
    chrome?: string;
125
    firefox?: string;
126
    chromiumedge?: string;
127
    ie?: string;
128
    edge?: string;
129
  };
130
}
131
```
132

133
**Usage Example:**
134

135
```typescript
136
// The launcher is typically not used directly, but through WebdriverIO service configuration
137
const launcher = new SeleniumStandaloneLauncher(
138
  { drivers: { chrome: true } },
139
  [{ browserName: "chrome" }],
140
  { outputDir: "./logs" }
141
);
142

143
await launcher.onPrepare({ watch: false } as any);
144
// Selenium server is now running and capabilities are configured
145
launcher.onComplete();
146
// Selenium server is stopped
147
```
148

149
### Configuration Options
150

151
Service configuration interface for customizing Selenium server behavior.
152

153
```typescript { .api }
154
/**
155
 * Configuration options for the Selenium Standalone service
156
 */
157
interface SeleniumStandaloneOptions {
158
  /** Path where Selenium server logs should be stored (Note: Implementation uses WebdriverIO outputDir instead) */
159
  logs?: string;
160
  
161
  /** Arguments passed directly to selenium-standalone install() */
162
  installArgs?: Partial<InstallOpts>;
163
  
164
  /** Arguments passed directly to selenium-standalone start() */
165
  args?: Partial<StartOpts>;
166
  
167
  /** Skip automatic selenium-standalone server installation */
168
  skipSeleniumInstall?: boolean;
169
  
170
  /** Simplified browser driver version configuration */
171
  drivers?: {
172
    chrome?: string | boolean;
173
    firefox?: string | boolean;
174
    chromiumedge?: string | boolean;
175
    ie?: string | boolean;
176
    edge?: string | boolean;
177
  };
178
}
179
```
180

181
**Configuration Examples:**
182

183
```typescript
184
// Simplified mode - easy driver configuration
185
const simpleConfig: SeleniumStandaloneOptions = {
186
  drivers: {
187
    chrome: true,           // Use default/latest version
188
    firefox: "0.33.0",      // Use specific version
189
    chromiumedge: "latest"  // Use latest version
190
  }
191
};
192

193
// Advanced mode - full control over selenium-standalone options
194
const advancedConfig: SeleniumStandaloneOptions = {
195
  skipSeleniumInstall: false,
196
  installArgs: {
197
    version: "4.0.0",
198
    drivers: {
199
      chrome: { version: "91.0.4472.101" }
200
    }
201
  },
202
  args: {
203
    seleniumArgs: ["-host", "127.0.0.1", "-port", "4444"]
204
  }
205
};
206
```
207

208
### Utility Functions
209

210
Core utility functions for file path resolution and capability validation.
211

212
```typescript { .api }
213
/**
214
 * Resolves the given path into an absolute path and appends the default filename as fallback when the provided path is a directory
215
 * @param filePath - Relative file or directory path
216
 * @param defaultFilename - Default file name when filePath is a directory  
217
 * @returns Absolute file path
218
 */
219
function getFilePath(filePath: string, defaultFilename: string): string;
220

221
/**
222
 * Find whether a browser session could be supported by the selenium-standalone service
223
 * @param capabilities - Capabilities used for the session
224
 * @returns True if capabilities suggest a supported platform
225
 */
226
function hasCapsWithSupportedBrowser(capabilities: Capabilities.Capabilities): boolean;
227
```
228

229
**Usage Examples:**
230

231
```typescript
232
import { getFilePath, hasCapsWithSupportedBrowser } from "@wdio/selenium-standalone-service";
233

234
// Resolve file path for logs
235
const logPath = getFilePath("./logs", "selenium.log");
236
// Result: "/absolute/path/to/logs/selenium.log"
237

238
// Check if capabilities are supported
239
const isSupported = hasCapsWithSupportedBrowser({ browserName: "chrome" });
240
// Result: true
241

242
const isUnsupported = hasCapsWithSupportedBrowser({ browserName: "opera" });
243
// Result: false
244
```
245

246
### Constants
247

248
Key constants used by the service.
249

250
```typescript { .api }
251
/** Default connection configuration for local Selenium server */
252
const DEFAULT_CONNECTION: {
253
  protocol: 'http';
254
  hostname: 'localhost';
255
  port: 4444;
256
  path: '/wd/hub';
257
};
258

259
/** Default log filename: 'wdio-selenium-standalone.log' */
260
const DEFAULT_LOG_FILENAME: 'wdio-selenium-standalone.log';
261

262
/** List of browser names supported by the service */
263
const SUPPORTED_CAPABILITIES: [
264
  'chrome',
265
  'googlechrome', 
266
  'firefox',
267
  'edge',
268
  'msedge',
269
  'microsoftedge',
270
  'microsoft edge',
271
  'safari',
272
  'webkit'
273
];
274
```
275

276

277
## Type Definitions
278

279
```typescript { .api }
280
/** Arguments for selenium-standalone start() method */
281
type SeleniumStartArgs = Partial<import('selenium-standalone').StartOpts>;
282

283
/** Arguments for selenium-standalone install() method */
284
type SeleniumInstallArgs = Partial<import('selenium-standalone').InstallOpts>;
285

286
/** Browser driver configuration for simplified mode */
287
type BrowserDrivers = {
288
  chrome?: string | boolean;
289
  firefox?: string | boolean;
290
  chromiumedge?: string | boolean;
291
  ie?: string | boolean;
292
  edge?: string | boolean;
293
};
294

295
/** External WebdriverIO types */
296
type Capabilities = import('@wdio/types').Capabilities;
297
type Options = import('@wdio/types').Options;
298
type Services = import('@wdio/types').Services;
299

300
/** External selenium-standalone types */
301
type InstallOpts = import('selenium-standalone').InstallOpts;
302
type StartOpts = import('selenium-standalone').StartOpts;
303
type ChildProcess = import('selenium-standalone').ChildProcess;
304
```
305

306
## Global Type Extensions
307

308
```typescript { .api }
309
declare global {
310
  namespace WebdriverIO {
311
    /** 
312
     * Extended service options interface
313
     * Note: 'args' property is omitted due to conflicts with Appium service
314
     */
315
    interface ServiceOption extends Omit<SeleniumStandaloneOptions, 'args'> {}
316
  }
317
}
318
```
319

320
## Error Handling
321

322
The service handles Selenium-related errors by:
323
- Logging errors through `@wdio/logger`
324
- Calling `process.exit(1)` on critical installation/startup failures
325
- Gracefully stopping the Selenium process during cleanup
326
- Supporting both watch mode and standard execution modes
327

328
**Common Error Scenarios:**
329
- Selenium installation failures (network issues, permissions)
330
- Port conflicts when starting Selenium server
331
- Driver installation failures for specific browser versions
332
- Process cleanup issues during test interruption