feat: Add Safari driver options (#1576)

Author: mykola-mokhnach

src/main/java/io/appium/java_client/safari/SafariDriver.java

@@ -0,0 +1,87 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.safari;
+
+import io.appium.java_client.AppiumDriver;
+import io.appium.java_client.remote.AutomationName;
+import io.appium.java_client.service.local.AppiumDriverLocalService;
+import io.appium.java_client.service.local.AppiumServiceBuilder;
+import org.openqa.selenium.Capabilities;
+import org.openqa.selenium.Platform;
+import org.openqa.selenium.remote.HttpCommandExecutor;
+import org.openqa.selenium.remote.http.HttpClient;
+
+import java.net.URL;
+
+/**
+ * GeckoDriver is an officially supported Appium driver
+ * created to automate mobile Safari browser. The driver uses W3C
+ * WebDriver protocol and is built on top of Apple's safaridriver
+ * server. Read https://github.com/appium/appium-safari-driver
+ * for more details on how to configure and use it.
+ *
+ * @since Appium 1.20.0
+ */
+public class SafariDriver extends AppiumDriver {
+    private static final String PLATFORM_NAME = Platform.IOS.toString();
+    private static final String AUTOMATION_NAME = AutomationName.SAFARI;
+
+    public SafariDriver(HttpCommandExecutor executor, Capabilities capabilities) {
+        super(executor, ensurePlatformAndAutomationNames(capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(URL remoteAddress, Capabilities capabilities) {
+        super(remoteAddress, ensurePlatformAndAutomationNames(
+                capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(URL remoteAddress, HttpClient.Factory httpClientFactory, Capabilities capabilities) {
+        super(remoteAddress, httpClientFactory, ensurePlatformAndAutomationNames(
+                capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(AppiumDriverLocalService service, Capabilities capabilities) {
+        super(service, ensurePlatformAndAutomationNames(
+                capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(AppiumDriverLocalService service, HttpClient.Factory httpClientFactory,
+                        Capabilities capabilities) {
+        super(service, httpClientFactory, ensurePlatformAndAutomationNames(
+                capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(AppiumServiceBuilder builder, Capabilities capabilities) {
+        super(builder, ensurePlatformAndAutomationNames(
+                capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(AppiumServiceBuilder builder, HttpClient.Factory httpClientFactory,
+                        Capabilities capabilities) {
+        super(builder, httpClientFactory, ensurePlatformAndAutomationNames(
+                capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(HttpClient.Factory httpClientFactory, Capabilities capabilities) {
+        super(httpClientFactory, ensurePlatformAndAutomationNames(
+                capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+
+    public SafariDriver(Capabilities capabilities) {
+        super(ensurePlatformAndAutomationNames(capabilities, PLATFORM_NAME, AUTOMATION_NAME));
+    }
+}

src/main/java/io/appium/java_client/safari/options/SafariOptions.java

@@ -0,0 +1,71 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.safari.options;
+
+import io.appium.java_client.remote.AutomationName;
+import io.appium.java_client.remote.options.BaseOptions;
+import io.appium.java_client.remote.options.SupportsAcceptInsecureCertsOption;
+import io.appium.java_client.remote.options.SupportsBrowserNameOption;
+import io.appium.java_client.remote.options.SupportsBrowserVersionOption;
+import io.appium.java_client.remote.options.SupportsPageLoadStrategyOption;
+import io.appium.java_client.remote.options.SupportsProxyOption;
+import io.appium.java_client.remote.options.SupportsSetWindowRectOption;
+import io.appium.java_client.remote.options.SupportsUnhandledPromptBehaviorOption;
+import org.openqa.selenium.Capabilities;
+import org.openqa.selenium.Platform;
+
+import java.util.Map;
+
+/**
+ * https://github.com/appium/appium-safari-driver#usage
+ */
+public class SafariOptions extends BaseOptions<SafariOptions> implements
+        SupportsBrowserNameOption<SafariOptions>,
+        SupportsBrowserVersionOption<SafariOptions>,
+        SupportsSafariPlatformVersionOption<SafariOptions>,
+        SupportsSafariPlatformBuildVersionOption<SafariOptions>,
+        SupportsSafariUseSimulatorOption<SafariOptions>,
+        SupportsSafariDeviceTypeOption<SafariOptions>,
+        SupportsSafariDeviceNameOption<SafariOptions>,
+        SupportsSafariDeviceUdidOption<SafariOptions>,
+        SupportsSafariAutomaticInspectionOption<SafariOptions>,
+        SupportsSafariAutomaticProfilingOption<SafariOptions>,
+        SupportsWebkitWebrtcOption<SafariOptions>,
+        SupportsAcceptInsecureCertsOption<SafariOptions>,
+        SupportsPageLoadStrategyOption<SafariOptions>,
+        SupportsSetWindowRectOption<SafariOptions>,
+        SupportsProxyOption<SafariOptions>,
+        SupportsUnhandledPromptBehaviorOption<SafariOptions> {
+    public SafariOptions() {
+        setCommonOptions();
+    }
+
+    public SafariOptions(Capabilities source) {
+        super(source);
+        setCommonOptions();
+    }
+
+    public SafariOptions(Map<String, ?> source) {
+        super(source);
+        setCommonOptions();
+    }
+
+    private void setCommonOptions() {
+        setPlatformName(Platform.IOS.toString());
+        setAutomationName(AutomationName.SAFARI);
+    }
+}

src/main/java/io/appium/java_client/safari/options/SupportsSafariAutomaticInspectionOption.java

@@ -0,0 +1,61 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.safari.options;
+
+import io.appium.java_client.remote.options.BaseOptions;
+import io.appium.java_client.remote.options.CanSetCapability;
+import org.openqa.selenium.Capabilities;
+
+import java.util.Optional;
+
+import static io.appium.java_client.internal.CapabilityHelpers.toSafeBoolean;
+
+public interface SupportsSafariAutomaticInspectionOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String SAFARI_AUTOMATIC_INSPECTION_OPTION = "safari:automaticInspection";
+
+    /**
+     * Enforces safaridriver to use Automatic Inspection.
+     *
+     * @return self instance for chaining.
+     */
+    default T safariAutomaticInspection() {
+        return amend(SAFARI_AUTOMATIC_INSPECTION_OPTION, true);
+    }
+
+    /**
+     * This capability instructs Safari to preload the Web Inspector and JavaScript
+     * debugger in the background prior to returning a newly-created window.
+     * To pause the test's execution in JavaScript and bring up Web Inspector's
+     * Debugger tab, you can simply evaluate a debugger; statement in the test page.
+     *
+     * @param bool Whether to use automatic inspection.
+     * @return self instance for chaining.
+     */
+    default T setSafariAutomaticInspection(boolean bool) {
+        return amend(SAFARI_AUTOMATIC_INSPECTION_OPTION, bool);
+    }
+
+    /**
+     * Get whether to use automatic inspection.
+     *
+     * @return true or false.
+     */
+    default Optional<Boolean> doesSafariAutomaticInspection() {
+        return Optional.ofNullable(toSafeBoolean(getCapability(SAFARI_AUTOMATIC_INSPECTION_OPTION)));
+    }
+}

src/main/java/io/appium/java_client/safari/options/SupportsSafariAutomaticProfilingOption.java

@@ -0,0 +1,61 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.safari.options;
+
+import io.appium.java_client.remote.options.BaseOptions;
+import io.appium.java_client.remote.options.CanSetCapability;
+import org.openqa.selenium.Capabilities;
+
+import java.util.Optional;
+
+import static io.appium.java_client.internal.CapabilityHelpers.toSafeBoolean;
+
+public interface SupportsSafariAutomaticProfilingOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String SAFARI_AUTOMATIC_PROFILING_OPTION = "safari:automaticProfiling";
+
+    /**
+     * Enforces safaridriver to use Automatic Inspection.
+     *
+     * @return self instance for chaining.
+     */
+    default T safariAutomaticProfiling() {
+        return amend(SAFARI_AUTOMATIC_PROFILING_OPTION, true);
+    }
+
+    /**
+     * This capability instructs Safari to preload the Web Inspector and start
+     * a Timeline recording in the background prior to returning a newly-created
+     * window. To view the recording, open the Web Inspector through Safari's
+     * Develop menu.
+     *
+     * @param bool Whether to use automatic profiling.
+     * @return self instance for chaining.
+     */
+    default T setSafariAutomaticProfiling(boolean bool) {
+        return amend(SAFARI_AUTOMATIC_PROFILING_OPTION, bool);
+    }
+
+    /**
+     * Get whether to use automatic profiling.
+     *
+     * @return true or false.
+     */
+    default Optional<Boolean> doesSafariAutomaticProfiling() {
+        return Optional.ofNullable(toSafeBoolean(getCapability(SAFARI_AUTOMATIC_PROFILING_OPTION)));
+    }
+}

src/main/java/io/appium/java_client/safari/options/SupportsSafariDeviceNameOption.java

@@ -0,0 +1,52 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.safari.options;
+
+import io.appium.java_client.remote.options.BaseOptions;
+import io.appium.java_client.remote.options.CanSetCapability;
+import org.openqa.selenium.Capabilities;
+
+import java.util.Optional;
+
+public interface SupportsSafariDeviceNameOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String SAFARI_DEVICE_NAME_OPTION = "safari:deviceName";
+
+    /**
+     * safaridriver will only create a session using hosts whose device name
+     * matches the value of safari:deviceName. Device names are compared
+     * case-insensitively. NOTE: Device names for connected devices are shown in
+     * iTunes. If Xcode is installed, device names for connected devices are available
+     * via the output of instruments(1) and in the Devices and Simulators window
+     * (accessed in Xcode via "Window -&gt; Devices and Simulators").
+     *
+     * @param deviceName Device name.
+     * @return self instance for chaining.
+     */
+    default T setSafariDeviceName(String deviceName) {
+        return amend(SAFARI_DEVICE_NAME_OPTION, deviceName);
+    }
+
+    /**
+     * Get the name of the device.
+     *
+     * @return String representing the name of the device.
+     */
+    default Optional<String> getSafariDeviceName() {
+        return Optional.ofNullable((String) getCapability(SAFARI_DEVICE_NAME_OPTION));
+    }
+}

src/main/java/io/appium/java_client/safari/options/SupportsSafariDeviceTypeOption.java

@@ -0,0 +1,50 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.safari.options;
+
+import io.appium.java_client.remote.options.BaseOptions;
+import io.appium.java_client.remote.options.CanSetCapability;
+import org.openqa.selenium.Capabilities;
+
+import java.util.Optional;
+
+public interface SupportsSafariDeviceTypeOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String SAFARI_DEVICE_TYPE_OPTION = "safari:deviceType";
+
+    /**
+     * If the value of safari:deviceType is 'iPhone', safaridriver will only create a session
+     * using an iPhone device or iPhone simulator. If the value of safari:deviceType is 'iPad',
+     * safaridriver will only create a session using an iPad device or iPad simulator.
+     * Values of safari:deviceType are compared case-insensitively.
+     *
+     * @param deviceType Device type name.
+     * @return self instance for chaining.
+     */
+    default T setSafariDeviceType(String deviceType) {
+        return amend(SAFARI_DEVICE_TYPE_OPTION, deviceType);
+    }
+
+    /**
+     * Get the type of the device.
+     *
+     * @return String representing the type of the device.
+     */
+    default Optional<String> getSafariDeviceType() {
+        return Optional.ofNullable((String) getCapability(SAFARI_DEVICE_TYPE_OPTION));
+    }
+}