0
# Selenium Safari Driver
1

2
A WebDriver implementation that controls Safari browsers on macOS through a browser extension. Part of the Selenium WebDriver suite, this library enables automated testing and browser automation specifically for Safari 5.1+ and Safari Technology Preview.
3

4
## Package Information
5

6
- **Package Name**: selenium-safari-driver
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Maven Coordinates**: `org.seleniumhq.selenium:selenium-safari-driver:3.141.59`
10
- **Module**: `org.openqa.selenium.safari`
11

12
## Dependencies
13

14
```xml
15
<dependency>
16
    <groupId>org.seleniumhq.selenium</groupId>
17
    <artifactId>selenium-safari-driver</artifactId>
18
    <version>3.141.59</version>
19
</dependency>
20
```
21

22
## Core Imports
23

24
```java
25
import org.openqa.selenium.safari.SafariDriver;
26
import org.openqa.selenium.safari.SafariOptions;
27
import org.openqa.selenium.safari.SafariDriverService;
28
```
29

30
## Basic Usage
31

32
```java
33
import org.openqa.selenium.safari.SafariDriver;
34
import org.openqa.selenium.safari.SafariOptions;
35
import org.openqa.selenium.WebDriver;
36

37
// Basic Safari driver initialization
38
WebDriver driver = new SafariDriver();
39

40
// With Safari options
41
SafariOptions options = new SafariOptions();
42
options.setUseTechnologyPreview(true);
43
options.setAutomaticInspection(false);
44
WebDriver driver = new SafariDriver(options);
45

46
// Navigate and interact
47
driver.get("https://example.com");
48
String title = driver.getTitle();
49
driver.quit();
50
```
51

52
## Architecture
53

54
The Safari Driver is built around several key components:
55

56
- **SafariDriver**: Main WebDriver implementation extending RemoteWebDriver for Safari browser control
57
- **SafariOptions**: Configuration class for Safari-specific settings including Technology Preview support
58
- **SafariDriverService**: Service management for Safari driver executable lifecycle
59
- **WebDriverInfo**: Factory classes providing metadata and driver instantiation capabilities
60
- **Module System**: Java 9+ module integration with service providers for automatic discovery
61

62
## Capabilities
63

64
### Safari Driver
65

66
Main WebDriver implementation for controlling Safari browsers.
67

68
```java { .api }
69
public class SafariDriver extends RemoteWebDriver {
70
    /**
71
     * Initializes a new SafariDriver with default SafariOptions.
72
     */
73
    public SafariDriver();
74
    
75
    /**
76
     * Initializes a new SafariDriver using SafariOptions.
77
     * @param safariOptions Configuration options for the driver
78
     */
79
    public SafariDriver(SafariOptions safariOptions);
80
    
81
    /**
82
     * Initializes a new SafariDriver with preconfigured service.
83
     * @param safariService Preconfigured SafariDriverService
84
     */
85
    public SafariDriver(SafariDriverService safariService);
86
    
87
    /**
88
     * Full constructor with both service and options.
89
     * @param safariService Preconfigured SafariDriverService
90
     * @param safariOptions Configuration options for the driver
91
     */
92
    public SafariDriver(SafariDriverService safariService, SafariOptions safariOptions);
93
    
94
    /**
95
     * @deprecated Use SafariDriver(SafariOptions) instead
96
     * @param desiredCapabilities Capabilities requested of the driver
97
     */
98
    @Deprecated
99
    public SafariDriver(Capabilities desiredCapabilities);
100
    
101
    /**
102
     * File detection is not supported in Safari.
103
     * @throws WebDriverException Always throws, as file detection is not supported
104
     */
105
    @Override
106
    public void setFileDetector(FileDetector detector);
107
    
108
    /**
109
     * Opens a new window or tab without switching to it.
110
     * This method uses Safari-specific WebDriver commands to create windows.
111
     * @param type The type of window to open (TAB or WINDOW)
112
     * @return The window handle of the new window
113
     */
114
    @Beta
115
    public String newWindow(WindowType type);
116
    
117
    public enum WindowType {
118
        TAB, WINDOW
119
    }
120
}
121
```
122

123
### Safari Options
124

125
Configuration options for Safari browser automation.
126

127
```java { .api }
128
public class SafariOptions extends MutableCapabilities {
129
    /** Browser name constant for Safari Technology Preview */
130
    public static final String SAFARI_TECH_PREVIEW = "Safari Technology Preview";
131
    
132
    /** @deprecated Use constructor methods instead */
133
    @Deprecated
134
    public static final String CAPABILITY = "safari.options";
135
    
136
    /**
137
     * Default constructor for SafariOptions.
138
     */
139
    public SafariOptions();
140
    
141
    /**
142
     * Initialize SafariOptions from existing capabilities.
143
     * @param source Existing capabilities to copy from
144
     */
145
    public SafariOptions(Capabilities source);
146
    
147
    /**
148
     * Factory method to create SafariOptions from capabilities.
149
     * @param capabilities Capabilities to convert
150
     * @return New SafariOptions instance
151
     */
152
    public static SafariOptions fromCapabilities(Capabilities capabilities);
153
    
154
    /**
155
     * Merge additional capabilities into these options.
156
     * @param extraCapabilities Additional capabilities to merge
157
     * @return This SafariOptions instance for chaining
158
     */
159
    public SafariOptions merge(Capabilities extraCapabilities);
160
    
161
    /**
162
     * Enable or disable automatic inspection.
163
     * @param automaticInspection Whether to enable automatic inspection
164
     * @return This SafariOptions instance for chaining
165
     */
166
    public SafariOptions setAutomaticInspection(boolean automaticInspection);
167
    
168
    /**
169
     * Enable or disable automatic profiling.
170
     * @param automaticProfiling Whether to enable automatic profiling
171
     * @return This SafariOptions instance for chaining
172
     */
173
    public SafariOptions setAutomaticProfiling(boolean automaticProfiling);
174
    
175
    /**
176
     * Configure use of Safari Technology Preview.
177
     * @param useTechnologyPreview Whether to use Safari Technology Preview
178
     * @return This SafariOptions instance for chaining
179
     */
180
    public SafariOptions setUseTechnologyPreview(boolean useTechnologyPreview);
181
    
182
    /**
183
     * Set proxy configuration.
184
     * @param proxy Proxy configuration to use
185
     * @return This SafariOptions instance for chaining
186
     */
187
    public SafariOptions setProxy(Proxy proxy);
188
    
189
    /**
190
     * Get current automatic inspection setting.
191
     * @return Whether automatic inspection is enabled
192
     */
193
    public boolean getAutomaticInspection();
194
    
195
    /**
196
     * Get current automatic profiling setting.
197
     * @return Whether automatic profiling is enabled
198
     */
199
    public boolean getAutomaticProfiling();
200
    
201
    /**
202
     * Get current technology preview setting.
203
     * @return Whether Safari Technology Preview is enabled
204
     */
205
    public boolean getUseTechnologyPreview();
206
    
207
    /**
208
     * Set a capability with special handling for technology preview.
209
     * @param key Capability key
210
     * @param value Capability value
211
     */
212
    @Override
213
    public void setCapability(String key, Object value);
214
    
215
    /**
216
     * Set a boolean capability with special handling for technology preview.
217
     * @param key Capability key  
218
     * @param value Boolean capability value
219
     */
220
    @Override
221
    public void setCapability(String key, boolean value);
222
    
223
    /**
224
     * Serialize options to map representation.
225
     * @return Map representation of these options
226
     */
227
    public Map<String, Object> asMap();
228
}
229
```
230

231
### Safari Driver Service
232

233
Service management for Safari driver executable lifecycle.
234

235
```java { .api }
236
public class SafariDriverService extends DriverService {
237
    /**
238
     * Create a service with default options.
239
     * @return New SafariDriverService instance
240
     */
241
    public static SafariDriverService createDefaultService();
242
    
243
    /**
244
     * Create a service with specified SafariOptions.
245
     * @param options SafariOptions to configure the service
246
     * @return New SafariDriverService instance
247
     */
248
    public static SafariDriverService createDefaultService(SafariOptions options);
249
    
250
    /**
251
     * Create a service from capabilities.
252
     * @param caps Capabilities to configure the service
253
     * @return New SafariDriverService instance
254
     */
255
    public static SafariDriverService createDefaultService(Capabilities caps);
256
    
257
    /**
258
     * Wait for the driver service to become available.
259
     */
260
    @Override
261
    protected void waitUntilAvailable();
262
    
263
    public static class Builder extends DriverService.Builder<SafariDriverService, SafariDriverService.Builder> {
264
        /**
265
         * Score how well this builder supports the given capabilities.
266
         * @param capabilities Capabilities to score
267
         * @return Compatibility score
268
         */
269
        public int score(Capabilities capabilities);
270
        
271
        /**
272
         * Configure whether to use Safari Technology Preview.
273
         * @param useTechnologyPreview Whether to use Technology Preview
274
         * @return This builder instance for chaining
275
         */
276
        public SafariDriverService.Builder usingTechnologyPreview(boolean useTechnologyPreview);
277
        
278
        /**
279
         * Find the default Safari driver executable.
280
         * @return File representing the default executable
281
         */
282
        @Override
283
        protected File findDefaultExecutable();
284
        
285
        /**
286
         * Create command line arguments for the service.
287
         * @return List of command line arguments
288
         */
289
        @Override
290
        protected ImmutableList<String> createArgs();
291
        
292
        /**
293
         * Create the driver service instance.
294
         * @param exe Executable file
295
         * @param port Port number
296
         * @param args Command line arguments
297
         * @param environment Environment variables
298
         * @return New SafariDriverService instance
299
         */
300
        @Override
301
        protected SafariDriverService createDriverService(
302
            File exe, 
303
            int port, 
304
            ImmutableList<String> args, 
305
            ImmutableMap<String, String> environment
306
        );
307
    }
308
}
309
```
310

311
### Driver Factory and Discovery
312

313
WebDriverInfo implementations for driver discovery and instantiation.
314

315
```java { .api }
316
public class SafariDriverInfo implements WebDriverInfo {
317
    /**
318
     * Get the display name for this driver.
319
     * @return "Safari"
320
     */
321
    @Override
322
    public String getDisplayName();
323
    
324
    /**
325
     * Get the canonical capabilities for Safari.
326
     * @return Default Safari capabilities
327
     */
328
    @Override
329
    public Capabilities getCanonicalCapabilities();
330
    
331
    /**
332
     * Check if this driver supports the given capabilities.
333
     * @param capabilities Capabilities to check
334
     * @return Whether capabilities are supported
335
     */
336
    @Override
337
    public boolean isSupporting(Capabilities capabilities);
338
    
339
    /**
340
     * Check if Safari driver is available on this system.
341
     * @return Whether Safari driver is available
342
     */
343
    @Override
344
    public boolean isAvailable();
345
    
346
    /**
347
     * Get maximum simultaneous sessions supported.
348
     * @return 1 (Safari limitation)
349
     */
350
    @Override
351
    public int getMaximumSimultaneousSessions();
352
    
353
    /**
354
     * Create a Safari WebDriver instance.
355
     * @param capabilities Desired capabilities
356
     * @return Optional WebDriver instance
357
     */
358
    @Override
359
    public Optional<WebDriver> createDriver(Capabilities capabilities);
360
}
361

362
public class SafariTechPreviewDriverInfo implements WebDriverInfo {
363
    /**
364
     * Get the display name for this driver.
365
     * @return "Safari Technology Preview"
366
     */
367
    @Override
368
    public String getDisplayName();
369
    
370
    /**
371
     * Get the canonical capabilities for Safari Technology Preview.
372
     * @return Default Safari Technology Preview capabilities
373
     */
374
    @Override
375
    public Capabilities getCanonicalCapabilities();
376
    
377
    /**
378
     * Check if this driver supports the given capabilities.
379
     * @param capabilities Capabilities to check
380
     * @return Whether capabilities are supported
381
     */
382
    @Override
383
    public boolean isSupporting(Capabilities capabilities);
384
    
385
    /**
386
     * Check if Safari Technology Preview driver is available.
387
     * @return Whether Safari Technology Preview driver is available
388
     */
389
    @Override
390
    public boolean isAvailable();
391
    
392
    /**
393
     * Get maximum simultaneous sessions supported.
394
     * @return 1 (Safari limitation)
395
     */
396
    @Override
397
    public int getMaximumSimultaneousSessions();
398
    
399
    /**
400
     * Create a Safari Technology Preview WebDriver instance.
401
     * @param capabilities Desired capabilities
402
     * @return Optional WebDriver instance
403
     */
404
    @Override
405
    public Optional<WebDriver> createDriver(Capabilities capabilities);
406
}
407
```
408

409
### Exception Handling
410

411
Safari-specific exceptions for connection and service management.
412

413
```java { .api }
414
public class ConnectionClosedException extends WebDriverException {
415
    /**
416
     * Create an exception for Safari driver connection failures.
417
     * @param message Error message describing the connection failure
418
     */
419
    public ConnectionClosedException(String message);
420
}
421
```
422

423
## Usage Examples
424

425
### Basic Safari Automation
426

427
```java
428
import org.openqa.selenium.safari.SafariDriver;
429
import org.openqa.selenium.WebDriver;
430
import org.openqa.selenium.By;
431

432
public class BasicSafariExample {
433
    public static void main(String[] args) {
434
        // Create Safari driver
435
        WebDriver driver = new SafariDriver();
436
        
437
        try {
438
            // Navigate to a page
439
            driver.get("https://www.example.com");
440
            
441
            // Find and interact with elements
442
            String title = driver.getTitle();
443
            System.out.println("Page title: " + title);
444
            
445
            // Find element and click
446
            driver.findElement(By.linkText("More information...")).click();
447
            
448
        } finally {
449
            driver.quit();
450
        }
451
    }
452
}
453
```
454

455
### Safari Technology Preview
456

457
```java
458
import org.openqa.selenium.safari.SafariDriver;
459
import org.openqa.selenium.safari.SafariOptions;
460
import org.openqa.selenium.WebDriver;
461

462
public class SafariTechPreviewExample {
463
    public static void main(String[] args) {
464
        // Configure Safari Technology Preview
465
        SafariOptions options = new SafariOptions();
466
        options.setUseTechnologyPreview(true);
467
        options.setAutomaticInspection(false);
468
        options.setAutomaticProfiling(false);
469
        
470
        // Create driver with Technology Preview
471
        WebDriver driver = new SafariDriver(options);
472
        
473
        try {
474
            driver.get("https://developer.mozilla.org");
475
            // Test modern web features
476
        } finally {
477
            driver.quit();
478
        }
479
    }
480
}
481
```
482

483
### Custom Service Configuration
484

485
```java
486
import org.openqa.selenium.safari.SafariDriver;
487
import org.openqa.selenium.safari.SafariDriverService;
488
import org.openqa.selenium.safari.SafariOptions;
489

490
public class CustomServiceExample {
491
    public static void main(String[] args) {
492
        // Build custom service
493
        SafariDriverService service = new SafariDriverService.Builder()
494
            .usingTechnologyPreview(true)
495
            .usingPort(4444)
496
            .build();
497
        
498
        SafariOptions options = new SafariOptions();
499
        options.setAutomaticInspection(true);
500
        
501
        SafariDriver driver = new SafariDriver(service, options);
502
        
503
        try {
504
            driver.get("https://webkit.org");
505
        } finally {
506
            driver.quit();
507
            service.stop();
508
        }
509
    }
510
}
511
```
512

513
### Remote WebDriver with Safari
514

515
```java
516
import org.openqa.selenium.remote.RemoteWebDriver;
517
import org.openqa.selenium.safari.SafariOptions;
518
import java.net.URL;
519

520
public class RemoteSafariExample {
521
    public static void main(String[] args) throws Exception {
522
        SafariOptions options = new SafariOptions();
523
        options.setUseTechnologyPreview(false);
524
        
525
        // Connect to remote Selenium Grid
526
        RemoteWebDriver driver = new RemoteWebDriver(
527
            new URL("http://localhost:4444/wd/hub"), 
528
            options
529
        );
530
        
531
        try {
532
            driver.get("https://selenium.dev");
533
        } finally {
534
            driver.quit();
535
        }
536
    }
537
}
538
```
539

540
## Types
541

542
### Core WebDriver Types
543

544
```java { .api }
545
// From org.openqa.selenium
546
interface WebDriver {
547
    void get(String url);
548
    String getCurrentUrl();
549
    String getTitle();
550
    void quit();
551
    WebElement findElement(By by);
552
    List<WebElement> findElements(By by);
553
    // ... other standard WebDriver methods
554
}
555

556
// From org.openqa.selenium.remote
557
class RemoteWebDriver implements WebDriver {
558
    protected RemoteWebDriver();
559
    public RemoteWebDriver(Capabilities capabilities);
560
    public RemoteWebDriver(URL remoteAddress, Capabilities capabilities);
561
    // ... WebDriver implementation methods
562
}
563

564
// From org.openqa.selenium
565
interface WebDriverInfo {
566
    String getDisplayName();
567
    Capabilities getCanonicalCapabilities();
568
    boolean isSupporting(Capabilities capabilities);
569
    boolean isAvailable();
570
    int getMaximumSimultaneousSessions();
571
    Optional<WebDriver> createDriver(Capabilities capabilities);
572
}
573
```
574

575
### Capabilities and Configuration
576

577
```java { .api }
578
// From org.openqa.selenium.Capabilities
579
interface Capabilities {
580
    String getBrowserName();
581
    String getVersion();
582
    String getPlatform();
583
    boolean is(String capabilityName);
584
    Object getCapability(String capabilityName);
585
    Map<String, Object> asMap();
586
}
587

588
// From org.openqa.selenium.MutableCapabilities
589
class MutableCapabilities implements Capabilities {
590
    public void setCapability(String key, Object value);
591
    public void setCapability(String key, boolean value);
592
    public Capabilities merge(Capabilities other);
593
}
594

595
// From org.openqa.selenium.Proxy
596
class Proxy {
597
    public enum ProxyType { DIRECT, MANUAL, PAC, AUTODETECT, SYSTEM }
598
    public void setHttpProxy(String httpProxy);
599
    public void setSslProxy(String sslProxy);
600
    public void setFtpProxy(String ftpProxy);
601
    public void setNoProxy(String noProxy);
602
}
603
```
604

605
### Service and Builder Types
606

607
```java { .api }
608
// From org.openqa.selenium.remote.service.DriverService
609
abstract class DriverService {
610
    public abstract void start();
611
    public abstract void stop();
612
    public abstract boolean isRunning();
613
    public abstract URL getUrl();
614
}
615

616
// From org.openqa.selenium.remote.service.DriverService.Builder
617
abstract class DriverService.Builder<DS extends DriverService, B extends DriverService.Builder<DS, B>> {
618
    public B usingPort(int port);
619
    public B withEnvironment(Map<String, String> environment);
620
    public B withLogFile(File logFile);
621
    public DS build();
622
}
623
```
624

625
### Exception Types
626

627
```java { .api }
628
// From org.openqa.selenium
629
class WebDriverException extends RuntimeException {
630
    public WebDriverException(String message);
631
    public WebDriverException(String message, Throwable cause);
632
}
633

634
// From org.openqa.selenium
635
class SessionNotCreatedException extends WebDriverException {
636
    public SessionNotCreatedException(String message);
637
    public SessionNotCreatedException(String message, Throwable cause);
638
}
639

640
// From org.openqa.selenium
641
class InvalidArgumentException extends WebDriverException {
642
    public InvalidArgumentException(String message);
643
    public InvalidArgumentException(String message, Throwable cause);
644
}
645
```
646

647
### Utility Types
648

649
```java { .api }
650
// From org.openqa.selenium.remote
651
class FileDetector {
652
    public File getLocalFile(CharSequence... keySequence);
653
}
654

655
// Java Standard Library Types
656
interface Optional<T> {
657
    static <T> Optional<T> empty();
658
    static <T> Optional<T> of(T value);
659
    boolean isPresent();
660
    T get();
661
}
662

663
interface List<E> extends Collection<E> {
664
    // Standard List interface methods
665
}
666

667
interface Map<K, V> {
668
    V put(K key, V value);
669
    V get(Object key);
670
    Set<K> keySet();
671
    Collection<V> values();
672
}
673

674
// From com.google.common.collect (Guava)
675
interface ImmutableList<E> extends List<E> {
676
    static <E> ImmutableList<E> of();
677
    static <E> ImmutableList<E> of(E element);
678
    // Immutable list implementation
679
}
680

681
interface ImmutableMap<K, V> extends Map<K, V> {
682
    static <K, V> ImmutableMap<K, V> of();
683
    static <K, V> ImmutableMap<K, V> of(K key, V value);
684
    // Immutable map implementation
685
}
686

687
// Java Standard Library
688
class File {
689
    public File(String pathname);
690
    public boolean exists();
691
    public String getAbsolutePath();
692
}
693

694
class URL {
695
    public URL(String spec);
696
    public String toString();
697
}
698
```
699

700
## Error Handling
701

702
Common exceptions when working with Safari Driver:
703

704
- **WebDriverException**: General WebDriver errors, including file detection attempts
705
- **ConnectionClosedException**: Safari-specific connection failures
706
- **SessionNotCreatedException**: When Safari driver service cannot start
707
- **InvalidArgumentException**: Invalid capabilities or configuration
708

709
```java
710
try {
711
    SafariDriver driver = new SafariDriver(options);
712
    // Driver operations
713
} catch (ConnectionClosedException e) {
714
    // Safari connection failed
715
    System.err.println("Safari connection failed: " + e.getMessage());
716
} catch (WebDriverException e) {
717
    // General WebDriver error
718
    System.err.println("WebDriver error: " + e.getMessage());
719
}
720
```
721

722
## Platform Requirements
723

724
- **Operating System**: macOS only
725
- **Safari Version**: 5.1 or later
726
- **Safari Technology Preview**: Optional, for testing cutting-edge features
727
- **System Permissions**: Safari must allow automation (enabled in Develop menu)
728
- **WebDriver Support**: Built into Safari on macOS 10.12+