feat: Add Windows driver options (#1564)

Author: mykola-mokhnach

src/main/java/io/appium/java_client/android/options/app/ActivityOptions.java

@@ -16,7 +16,7 @@
 
 package io.appium.java_client.android.options.app;
 
-import io.appium.java_client.android.options.BaseMapOptionData;
+import io.appium.java_client.remote.options.BaseMapOptionData;
 
 import java.util.Map;
 import java.util.Optional;

src/main/java/io/appium/java_client/android/options/app/IntentOptions.java

@@ -16,7 +16,7 @@
 
 package io.appium.java_client.android.options.app;
 
-import io.appium.java_client.android.options.BaseMapOptionData;
+import io.appium.java_client.remote.options.BaseMapOptionData;
 
 import java.util.List;
 import java.util.Map;

src/main/java/io/appium/java_client/android/options/localization/AppLocale.java

@@ -16,10 +16,8 @@
 
 package io.appium.java_client.android.options.localization;
 
-import io.appium.java_client.android.options.BaseMapOptionData;
+import io.appium.java_client.remote.options.BaseMapOptionData;
 
-import java.util.Collections;
-import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
 

src/main/java/io/appium/java_client/android/options/BaseMapOptionData.java renamed to src/main/java/io/appium/java_client/remote/options/BaseMapOptionData.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package io.appium.java_client.android.options;
+package io.appium.java_client.remote.options;
 
 import com.google.gson.GsonBuilder;
 
@@ -24,7 +24,7 @@
 import java.util.Optional;
 
 public abstract class BaseMapOptionData<T extends BaseMapOptionData<T>> {
-    protected Map<String, Object> options;
+    private Map<String, Object> options;
 
     public BaseMapOptionData() {
     }

src/main/java/io/appium/java_client/windows/options/RunScript.java

@@ -0,0 +1,69 @@
+/*
+ * 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.windows.options;
+
+import io.appium.java_client.remote.options.BaseMapOptionData;
+
+import java.util.Map;
+import java.util.Optional;
+
+public class RunScript extends BaseMapOptionData<RunScript> {
+    public RunScript() {
+    }
+
+    public RunScript(Map<String, Object> options) {
+        super(options);
+    }
+
+    /**
+     * Allows to provide a multiline PowerShell script.
+     *
+     * @param script A valid PowerShell script.
+     * @return self instance for chaining.
+     */
+    public RunScript withScript(String script) {
+        return assignOptionValue("script", script);
+    }
+
+    /**
+     * Get a multiline PowerShell script.
+     *
+     * @return PowerShell script.
+     */
+    public Optional<String> getScript() {
+        return getOptionValue("script");
+    }
+
+    /**
+     * Allows to provide a single-line PowerShell script.
+     *
+     * @param command A valid PowerShell script.
+     * @return self instance for chaining.
+     */
+    public RunScript withCommand(String command) {
+        return assignOptionValue("command", command);
+    }
+
+    /**
+     * Get a single-line PowerShell script.
+     *
+     * @return PowerShell script.
+     */
+    public Optional<String> getCommand() {
+        return getOptionValue("command");
+    }
+}

src/main/java/io/appium/java_client/windows/options/SupportsAppArgumentsOption.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.windows.options;
+
+import io.appium.java_client.remote.options.BaseOptions;
+import io.appium.java_client.remote.options.CanSetCapability;
+import org.openqa.selenium.Capabilities;
+
+import java.net.URL;
+import java.util.Optional;
+
+public interface SupportsAppArgumentsOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String APP_ARGUMENTS_OPTION = "appArguments";
+
+    /**
+     * Application arguments string.
+     *
+     * @param args E.g. "/?"
+     * @return self instance for chaining.
+     */
+    default T setAppArguments(String args) {
+        return amend(APP_ARGUMENTS_OPTION, args);
+    }
+
+    /**
+     * Get application arguments.
+     *
+     * @return Application arguments.
+     */
+    default Optional<String> setAppArguments() {
+        return Optional.ofNullable((String) getCapability(APP_ARGUMENTS_OPTION));
+    }
+}

src/main/java/io/appium/java_client/windows/options/SupportsAppTopLevelWindowOption.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.windows.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 SupportsAppTopLevelWindowOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String APP_TOP_LEVEL_WINDOW_OPTION = "appTopLevelWindow";
+
+    /**
+     * Set the hexadecimal handle of an existing application top level
+     * window to attach to, for example 0x12345 (should be of string type).
+     * Either this capability or app one must be provided on session startup.
+     *
+     * @param identifier E.g. "0x12345".
+     * @return self instance for chaining.
+     */
+    default T setAppTopLevelWindow(String identifier) {
+        return amend(APP_TOP_LEVEL_WINDOW_OPTION, identifier);
+    }
+
+    /**
+     * Get the hexadecimal handle of an existing application top level
+     * window to attach to.
+     *
+     * @return Top level window handle.
+     */
+    default Optional<String> getAppTopLevelWindow() {
+        return Optional.ofNullable((String) getCapability(APP_TOP_LEVEL_WINDOW_OPTION));
+    }
+}

src/main/java/io/appium/java_client/windows/options/SupportsAppWorkingDirOption.java

@@ -0,0 +1,49 @@
+/*
+ * 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.windows.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 SupportsAppWorkingDirOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String APP_WORKING_DIR_OPTION = "appWorkingDir";
+
+    /**
+     * Full path to the folder, which is going to be set as the working
+     * dir for the application under test. This is only applicable for classic apps.
+     *
+     * @param path Existing folder path on the server file system.
+     * @return self instance for chaining.
+     */
+    default T setAppWorkingDir(String path) {
+        return amend(APP_WORKING_DIR_OPTION, path);
+    }
+
+    /**
+     * Get the full path to the folder, which is going to be set as the working
+     * dir for the application under test.
+     *
+     * @return Folder path on the server file system.
+     */
+    default Optional<String> getAppWorkingDir() {
+        return Optional.ofNullable((String) getCapability(APP_WORKING_DIR_OPTION));
+    }
+}

src/main/java/io/appium/java_client/windows/options/SupportsCreateSessionTimeoutOption.java

@@ -0,0 +1,55 @@
+/*
+ * 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.windows.options;
+
+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;
+
+import static io.appium.java_client.internal.CapabilityHelpers.toDuration;
+
+public interface SupportsCreateSessionTimeoutOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String CREATE_SESSION_TIMEOUT_OPTION = "createSessionTimeout";
+
+    /**
+     * Set the timeout used to retry Appium Windows Driver session startup.
+     * This capability could be used as a workaround for the long startup times
+     * of UWP applications (aka Failed to locate opened application window
+     * with appId: TestCompany.my_app4!App, and processId: 8480). Default value is 20000ms.
+     *
+     * @param timeout The timeout value.
+     * @return self instance for chaining.
+     */
+    default T setCreateSessionTimeout(Duration timeout) {
+        return amend(CREATE_SESSION_TIMEOUT_OPTION, timeout.toMillis());
+    }
+
+    /**
+     * Get the timeout used to retry Appium Windows Driver session startup.
+     *
+     * @return The timeout value.
+     */
+    default Optional<Duration> getCreateSessionTimeout() {
+        return Optional.ofNullable(
+                toDuration(getCapability(CREATE_SESSION_TIMEOUT_OPTION))
+        );
+    }
+}

src/main/java/io/appium/java_client/windows/options/SupportsMsExperimentalWebDriverOption.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.windows.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 SupportsMsExperimentalWebDriverOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String MS_EXPERIMENTAL_WEBDRIVER_OPTION = "ms:experimental-webdriver";
+
+    /**
+     * Enforce to enable experimental driver features and optimizations.
+     *
+     * @return self instance for chaining.
+     */
+    default T experimentalWebDriver() {
+        return amend(MS_EXPERIMENTAL_WEBDRIVER_OPTION, true);
+    }
+
+    /**
+     * Enables experimental features and optimizations. See Appium Windows
+     * Driver release notes for more details on this capability. false by default.
+     *
+     * @param value Whether to enable experimental features and optimizations.
+     * @return self instance for chaining.
+     */
+    default T setExperimentalWebDriver(boolean value) {
+        return amend(MS_EXPERIMENTAL_WEBDRIVER_OPTION, value);
+    }
+
+    /**
+     * Get whether to enable experimental features and optimizations.
+     *
+     * @return True or false.
+     */
+    default Optional<Boolean> isExperimentalWebDriver() {
+        return Optional.ofNullable(toSafeBoolean(getCapability(MS_EXPERIMENTAL_WEBDRIVER_OPTION)));
+    }
+}