Selenium OS

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.

Package Information

• Package Name: selenium-os
• Package Type: Maven
• Language: Java
• Installation:

  <dependency>
      <groupId>org.seleniumhq.selenium</groupId>
      <artifactId>selenium-os</artifactId>
      <version>4.33.0</version>
  </dependency>

Core Imports

import org.openqa.selenium.os.ExternalProcess;
import org.openqa.selenium.os.ExecutableFinder;
import org.openqa.selenium.os.CommandLine;  // Deprecated

Basic Usage

import org.openqa.selenium.os.ExternalProcess;
import org.openqa.selenium.os.ExecutableFinder;
import java.time.Duration;
import java.util.Arrays;

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

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

// Wait for process and get output  
boolean completed = process.waitFor(Duration.ofSeconds(30));
if (completed) {
    String output = process.getOutput();
    int exitCode = process.exitValue();
    System.out.println("Process completed with exit code: " + exitCode);
} else {
    process.shutdown();  // Force shutdown if not completed
}

Architecture

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

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

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

Capabilities

Modern Process Management

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

public static ExternalProcess.Builder builder();

public class ExternalProcess.Builder {
    public Builder command(String executable, List<String> arguments);
    public Builder environment(String name, String value);
    public Builder directory(File directory);
    public Builder copyOutputTo(OutputStream stream);
    public Builder bufferSize(int toKeep);
    public ExternalProcess start() throws UncheckedIOException;
}

public class ExternalProcess {
    public String getOutput();
    public String getOutput(Charset encoding);
    public boolean isAlive();
    public boolean waitFor(Duration duration) throws InterruptedException;
    public int exitValue();
    public void shutdown();
    public void shutdown(Duration timeout);
}

Modern Process Management

Executable Discovery

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

public class ExecutableFinder {
    public String find(String named);
}

Executable Discovery

Legacy Process Management

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

@Deprecated
public class CommandLine {
    public CommandLine(String executable, String... args);
    public void setEnvironmentVariable(String name, String value);
    public void execute();
    public void executeAsync();
    public boolean isRunning();
    public int getExitCode();
    public String getStdOut();
    public int destroy();
}

Legacy Process Management

Platform-Specific Behavior

The package automatically handles platform differences:

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

Exception Handling

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