0
# Selenium OS
1

2
Operating system utilities for Selenium WebDriver, providing cross-platform process management and executable discovery capabilities. This package handles the low-level operating system interactions required for browser automation, including launching external processes, finding executables on the system PATH, and managing process lifecycles across Windows, macOS, and Linux platforms.
3

4
## Package Information
5

6
- **Package Name**: selenium-os
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>org.seleniumhq.selenium</groupId>
13
      <artifactId>selenium-os</artifactId>
14
      <version>4.33.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.openqa.selenium.os.ExternalProcess;
22
import org.openqa.selenium.os.ExecutableFinder;
23
import org.openqa.selenium.os.CommandLine;  // Deprecated
24
```
25

26
## Basic Usage
27

28
```java
29
import org.openqa.selenium.os.ExternalProcess;
30
import org.openqa.selenium.os.ExecutableFinder;
31
import java.time.Duration;
32
import java.util.Arrays;
33

34
// Find an executable on the system PATH
35
ExecutableFinder finder = new ExecutableFinder();
36
String chromePath = finder.find("chromedriver");
37

38
// Launch and manage an external process (modern API)
39
ExternalProcess process = ExternalProcess.builder()
40
    .command(chromePath, Arrays.asList("--port=9515", "--verbose"))
41
    .environment("LOG_LEVEL", "INFO")
42
    .directory("/tmp")
43
    .bufferSize(8192)
44
    .start();
45

46
// Wait for process and get output  
47
boolean completed = process.waitFor(Duration.ofSeconds(30));
48
if (completed) {
49
    String output = process.getOutput();
50
    int exitCode = process.exitValue();
51
    System.out.println("Process completed with exit code: " + exitCode);
52
} else {
53
    process.shutdown();  // Force shutdown if not completed
54
}
55
```
56

57
## Architecture
58

59
The selenium-os package provides two APIs for process management:
60

61
- **Modern API**: `ExternalProcess` with builder pattern for new implementations
62
- **Legacy API**: `CommandLine` and `OsProcess` for backward compatibility (deprecated)
63
- **Executable Discovery**: `ExecutableFinder` for locating executables across platforms
64
- **Cross-Platform Support**: Handles platform-specific differences for Windows, macOS, and Linux
65

66
The modern `ExternalProcess` API provides better resource management, builder pattern configuration, and improved error handling compared to the deprecated legacy classes.
67

68
## Capabilities
69

70
### Modern Process Management
71

72
Modern, builder-pattern-based external process execution with improved resource management, flexible configuration, and robust error handling.
73

74
```java { .api }
75
public static ExternalProcess.Builder builder();
76

77
public class ExternalProcess.Builder {
78
    public Builder command(String executable, List<String> arguments);
79
    public Builder environment(String name, String value);
80
    public Builder directory(File directory);
81
    public Builder copyOutputTo(OutputStream stream);
82
    public Builder bufferSize(int toKeep);
83
    public ExternalProcess start() throws UncheckedIOException;
84
}
85

86
public class ExternalProcess {
87
    public String getOutput();
88
    public String getOutput(Charset encoding);
89
    public boolean isAlive();
90
    public boolean waitFor(Duration duration) throws InterruptedException;
91
    public int exitValue();
92
    public void shutdown();
93
    public void shutdown(Duration timeout);
94
}
95
```
96

97
[Modern Process Management](./modern-process.md)
98

99
### Executable Discovery
100

101
Cross-platform utility for finding executables on the system PATH with automatic handling of platform-specific file extensions.
102

103
```java { .api }
104
public class ExecutableFinder {
105
    public String find(String named);
106
}
107
```
108

109
[Executable Discovery](./executable-finder.md) 
110

111
### Legacy Process Management
112

113
Deprecated command-line execution utilities maintained for backward compatibility. Use the modern `ExternalProcess` API for new implementations.
114

115
```java { .api }
116
@Deprecated
117
public class CommandLine {
118
    public CommandLine(String executable, String... args);
119
    public void setEnvironmentVariable(String name, String value);
120
    public void execute();
121
    public void executeAsync();
122
    public boolean isRunning();
123
    public int getExitCode();
124
    public String getStdOut();
125
    public int destroy();
126
}
127
```
128

129
[Legacy Process Management](./legacy-process.md)
130

131
## Platform-Specific Behavior
132

133
The package automatically handles platform differences:
134

135
- **Windows**: Supports `.exe`, `.com`, `.bat`, `.cmd` extensions; uses `PATH` environment variable
136
- **macOS**: Reads additional paths from `/etc/paths`; uses `DYLD_LIBRARY_PATH` for dynamic libraries  
137
- **Linux/Unix**: Standard PATH-based discovery; uses `LD_LIBRARY_PATH` for dynamic libraries
138

139
## Exception Handling
140

141
- `UncheckedIOException`: Thrown by `ExternalProcess.Builder.start()` when process creation fails
142
- `IllegalArgumentException`: Thrown for null environment variable names or values
143
- `InterruptedException`: Thrown by wait operations when thread is interrupted
144
- `WebDriverException`: Thrown by legacy API for various process errors
145
- `TimeoutException`: Thrown by legacy API when operations exceed specified timeouts