chore: Start adding XCUITest driver options (#1551)

Author: mykola-mokhnach

src/main/java/io/appium/java_client/ios/options/XCUITestOptions.java

@@ -16,6 +16,12 @@
 
 package io.appium.java_client.ios.options;
 
+import io.appium.java_client.ios.options.app.SupportsAppInstallStrategyOption;
+import io.appium.java_client.ios.options.app.SupportsAppPushTimeoutOption;
+import io.appium.java_client.ios.options.app.SupportsBundleIdOption;
+import io.appium.java_client.ios.options.app.SupportsLocalizableStringsDirOption;
+import io.appium.java_client.ios.options.general.SupportsIncludeDeviceCapsToSessionInfoOption;
+import io.appium.java_client.ios.options.general.SupportsResetLocationServiceOption;
 import io.appium.java_client.remote.AutomationName;
 import io.appium.java_client.remote.MobilePlatform;
 import io.appium.java_client.remote.options.BaseOptions;
@@ -31,12 +37,34 @@
 import io.appium.java_client.remote.options.SupportsUdidOption;
 import org.openqa.selenium.Capabilities;
 
+/**
+ * https://github.com/appium/appium-xcuitest-driver#capabilities
+ */
 public class XCUITestOptions extends BaseOptions<XCUITestOptions> implements
-        SupportsAppOption<XCUITestOptions>, SupportsAutoWebViewOption<XCUITestOptions>,
-        SupportsClearSystemFilesOption<XCUITestOptions>, SupportsDeviceNameOption<XCUITestOptions>,
-        SupportsEnablePerformanceLoggingOption<XCUITestOptions>, SupportsLanguageOption<XCUITestOptions>,
-        SupportsLocaleOption<XCUITestOptions>, SupportsOrientationOption<XCUITestOptions>,
-        SupportsOtherAppsOption<XCUITestOptions>, SupportsUdidOption<XCUITestOptions> {
+        // General options: https://github.com/appium/appium-xcuitest-driver#general
+        SupportsDeviceNameOption<XCUITestOptions>,
+        SupportsUdidOption<XCUITestOptions>,
+        SupportsIncludeDeviceCapsToSessionInfoOption<XCUITestOptions>,
+        SupportsResetLocationServiceOption<XCUITestOptions>,
+        // Localization Options
+        SupportsLocalizableStringsDirOption<XCUITestOptions>,
+        SupportsLanguageOption<XCUITestOptions>,
+        SupportsLocaleOption<XCUITestOptions>,
+        // App Options: https://github.com/appium/appium-xcuitest-driver#app
+        SupportsAppOption<XCUITestOptions>,
+        SupportsBundleIdOption<XCUITestOptions>,
+        SupportsOtherAppsOption<XCUITestOptions>,
+        SupportsAppPushTimeoutOption<XCUITestOptions>,
+        SupportsAppInstallStrategyOption<XCUITestOptions>,
+        // TODO: WebDriverAgent options: https://github.com/appium/appium-xcuitest-driver#webdriveragent
+        // TODO: Simulator options: https://github.com/appium/appium-xcuitest-driver#simulator
+        SupportsOrientationOption<XCUITestOptions>,
+        // TODO: Web context options: https://github.com/appium/appium-xcuitest-driver#web-context
+        SupportsAutoWebViewOption<XCUITestOptions>,
+        // TODO: Other options: https://github.com/appium/appium-xcuitest-driver#other
+        SupportsClearSystemFilesOption<XCUITestOptions>,
+        SupportsEnablePerformanceLoggingOption<XCUITestOptions> {
+
     public XCUITestOptions() {
         setCommonOptions();
     }

src/main/java/io/appium/java_client/ios/options/app/SupportsAppInstallStrategyOption.java

@@ -0,0 +1,58 @@
+/*
+ * 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.ios.options.app;
+
+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 SupportsAppInstallStrategyOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String APP_INSTALL_STRATEGY_OPTION = "appInstallStrategy";
+
+    /**
+     * Select application installation strategy for real devices. The following
+     * strategies are supported:
+     *
+     * serial (default) - pushes app files to the device in a sequential order;
+     * this is the least performant strategy, although the most reliable;
+     *
+     * parallel - pushes app files simultaneously; this is usually the
+     * most performant strategy, but sometimes could not be very stable;
+     *
+     * ios-deploy - tells the driver to use a third-party tool ios-deploy to
+     * install the app; obviously the tool must be installed separately
+     * first and must be present in PATH before it could be used.
+     *
+     * @param strategy App installation strategy.
+     * @return self instance for chaining.
+     */
+    default T setAppInstallStrategy(String strategy) {
+        return amend(APP_INSTALL_STRATEGY_OPTION, strategy);
+    }
+
+    /**
+     * Get the app install strategy.
+     *
+     * @return App installation strategy.
+     */
+    default Optional<String> getAppInstallStrategy() {
+        return Optional.ofNullable((String) getCapability(APP_INSTALL_STRATEGY_OPTION));
+    }
+}

src/main/java/io/appium/java_client/ios/options/app/SupportsAppPushTimeoutOption.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.ios.options.app;
+
+import io.appium.java_client.internal.CapabilityHelpers;
+import io.appium.java_client.remote.options.BaseOptions;
+import io.appium.java_client.remote.options.CanSetCapability;
+import org.openqa.selenium.Capabilities;
+
+import java.time.Duration;
+import java.util.Optional;
+
+public interface SupportsAppPushTimeoutOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String APP_PUSH_TIMEOUT_OPTION = "appPushTimeout";
+
+    /**
+     * The timeout for application upload.
+     * Works for real devices only. The default value is 30000ms.
+     *
+     * @param timeout App push timeout.
+     * @return self instance for chaining.
+     */
+    default T setAppPushTimeout(Duration timeout) {
+        return amend(APP_PUSH_TIMEOUT_OPTION, timeout.toMillis());
+    }
+
+    /**
+     * Get maximum timeout for application upload.
+     *
+     * @return Timeout value.
+     */
+    default Optional<Duration> getAppPushTimeout() {
+        return Optional.ofNullable(
+                CapabilityHelpers.toDuration(getCapability(APP_PUSH_TIMEOUT_OPTION))
+        );
+    }
+}

src/main/java/io/appium/java_client/ios/options/app/SupportsBundleIdOption.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.ios.options.app;
+
+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 SupportsBundleIdOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String BUNDLE_ID_OPTION = "bundleId";
+
+    /**
+     * Bundle identifier of the app under test, for example com.mycompany.myapp.
+     * The capability value is calculated automatically if app is provided.
+     * If neither app nor bundleId capability is provided then XCUITest driver
+     * starts from the Home screen.
+     *
+     * @param identifier App identifier.
+     * @return self instance for chaining.
+     */
+    default T setBundleId(String identifier) {
+        return amend(BUNDLE_ID_OPTION, identifier);
+    }
+
+    /**
+     * Get the app bundle identifier.
+     *
+     * @return Identifier value.
+     */
+    default Optional<String> getBundleId() {
+        return Optional.ofNullable((String) getCapability(BUNDLE_ID_OPTION));
+    }
+}

src/main/java/io/appium/java_client/ios/options/app/SupportsLocalizableStringsDirOption.java

@@ -0,0 +1,48 @@
+/*
+ * 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.ios.options.app;
+
+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 SupportsLocalizableStringsDirOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String LOCALIZABLE_STRINGS_DIR_OPTION = "localizableStringsDir";
+
+    /**
+     * Where to look for localizable strings in the application bundle.
+     * Defaults to en.lproj.
+     *
+     * @param folder The resource folder name where the main locale strings are stored.
+     * @return self instance for chaining.
+     */
+    default T setLocalizableStringsDir(String folder) {
+        return amend(LOCALIZABLE_STRINGS_DIR_OPTION, folder);
+    }
+
+    /**
+     * Get the resource folder name where the main locale strings are stored.
+     *
+     * @return Folder name.
+     */
+    default Optional<String> getLocalizableStringsDir() {
+        return Optional.ofNullable((String) getCapability(LOCALIZABLE_STRINGS_DIR_OPTION));
+    }
+}

src/main/java/io/appium/java_client/ios/options/general/SupportsIncludeDeviceCapsToSessionInfoOption.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.ios.options.general;
+
+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 SupportsIncludeDeviceCapsToSessionInfoOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String INCLUDE_DEVICE_CAPS_TO_SESSION_INFO_OPTION = "includeDeviceCapsToSessionInfo";
+
+    /**
+     * Whether to include screen information as the result of Get Session Capabilities.
+     * It includes pixelRatio, statBarHeight and viewportRect, but
+     * it causes an extra API call to WDA which may increase the response time.
+     * Defaults to true.
+     *
+     * @param value Whether to include screen information as the result of Get Session Capabilities.
+     * @return self instance for chaining.
+     */
+    default T setIncludeDeviceCapsToSessionInfo(boolean value) {
+        return amend(INCLUDE_DEVICE_CAPS_TO_SESSION_INFO_OPTION, value);
+    }
+
+    /**
+     * Get whether to include screen information as the result of Get Session Capabilities.
+     *
+     * @return True or false.
+     */
+    default Optional<Boolean> doesIncludeDeviceCapsToSessionInfo() {
+        return Optional.ofNullable(toSafeBoolean(getCapability(INCLUDE_DEVICE_CAPS_TO_SESSION_INFO_OPTION)));
+    }
+}

src/main/java/io/appium/java_client/ios/options/general/SupportsResetLocationServiceOption.java

@@ -0,0 +1,59 @@
+/*
+ * 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.ios.options.general;
+
+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 SupportsResetLocationServiceOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String RESET_LOCATION_SERVICE_OPTION = "resetLocationService";
+
+    /**
+     * Set to reset the location service in the session deletion on real device.
+     *
+     * @return self instance for chaining.
+     */
+    default T resetLocationService() {
+        return amend(RESET_LOCATION_SERVICE_OPTION, true);
+    }
+
+    /**
+     * Whether reset the location service in the session deletion on real device.
+     * Defaults to false.
+     *
+     * @param value Whether to reset the location service in the session deletion on real device.
+     * @return self instance for chaining.
+     */
+    default T setResetLocationService(boolean value) {
+        return amend(RESET_LOCATION_SERVICE_OPTION, value);
+    }
+
+    /**
+     * Get whether to reset the location service in the session deletion on real device.
+     *
+     * @return True or false.
+     */
+    default Optional<Boolean> doesResetLocationService() {
+        return Optional.ofNullable(toSafeBoolean(getCapability(RESET_LOCATION_SERVICE_OPTION)));
+    }
+}