feat: Add Mac2 driver options (#1565)

src/main/java/io/appium/java_client/mac/options/Mac2Options.java

@@ -0,0 +1,60 @@
+/*
+ * 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.mac.options;
+
+import io.appium.java_client.remote.AutomationName;
+import io.appium.java_client.remote.MobilePlatform;
+import io.appium.java_client.remote.options.BaseOptions;
+import org.openqa.selenium.Capabilities;
+
+import java.util.Map;
+
+/**
+ * https://github.com/appium/appium-mac2-driver#capabilities
+ */
+public class Mac2Options extends BaseOptions<Mac2Options> implements
+        SupportsSystemPortOption<Mac2Options>,
+        SupportsSystemHostOption<Mac2Options>,
+        SupportsWebDriverAgentMacUrlOption<Mac2Options>,
+        SupportsBootstrapRootOption<Mac2Options>,
+        SupportsBundleIdOption<Mac2Options>,
+        SupportsArgumentsOption<Mac2Options>,
+        SupportsEnvironmentOption<Mac2Options>,
+        SupportsServerStartupTimeoutOption<Mac2Options>,
+        SupportsSkipAppKillOption<Mac2Options>,
+        SupportsShowServerLogsOption<Mac2Options>,
+        SupportsPrerunOption<Mac2Options>,
+        SupportsPostrunOption<Mac2Options> {
+    public Mac2Options() {
+        setCommonOptions();
+    }
+
+    public Mac2Options(Capabilities source) {
+        super(source);
+        setCommonOptions();
+    }
+
+    public Mac2Options(Map<String, ?> source) {
+        super(source);
+        setCommonOptions();
+    }
+
+    private void setCommonOptions() {
+        setPlatformName(MobilePlatform.MAC);
+        setAutomationName(AutomationName.MAC2);
+    }
+}

src/main/java/io/appium/java_client/mac/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.mac.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 AppleScript.
+     *
+     * @param script A valid AppleScript.
+     * @return self instance for chaining.
+     */
+    public RunScript withScript(String script) {
+        return assignOptionValue("script", script);
+    }
+
+    /**
+     * Get a multiline AppleScript.
+     *
+     * @return AppleScript snippet.
+     */
+    public Optional<String> getScript() {
+        return getOptionValue("script");
+    }
+
+    /**
+     * Allows to provide a single-line AppleScript.
+     *
+     * @param command A valid AppleScript.
+     * @return self instance for chaining.
+     */
+    public RunScript withCommand(String command) {
+        return assignOptionValue("command", command);
+    }
+
+    /**
+     * Get a single-line AppleScript.
+     *
+     * @return AppleScript snippet.
+     */
+    public Optional<String> getCommand() {
+        return getOptionValue("command");
+    }
+}

src/main/java/io/appium/java_client/mac/options/SupportsArgumentsOption.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.mac.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.List;
+import java.util.Optional;
+
+public interface SupportsArgumentsOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String ARGUMENTS_OPTION = "arguments";
+
+    /**
+     * Array of application command line arguments. This capability is
+     * only going to be applied if the application is not running on session startup.
+     *
+     * @param arguments E.g. ["--help"].
+     * @return self instance for chaining.
+     */
+    default T setArguments(List<String> arguments) {
+        return amend(ARGUMENTS_OPTION, arguments);
+    }
+
+    /**
+     * Get the array of application command line arguments.
+     *
+     * @return Application arguments.
+     */
+    default Optional<List<String>> getArguments() {
+        //noinspection unchecked
+        return Optional.ofNullable((List<String>) getCapability(ARGUMENTS_OPTION));
+    }
+}

src/main/java/io/appium/java_client/mac/options/SupportsBootstrapRootOption.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.mac.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 SupportsBootstrapRootOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String BOOTSTRAP_ROOT_OPTION = "bootstrapRoot";
+
+    /**
+     * The full path to WebDriverAgentMac root folder where Xcode project
+     * of the server sources lives. By default, this project is located in
+     * the same folder where the corresponding driver Node.js module lives.
+     *
+     * @param path The full path to WebDriverAgentMac root folder.
+     * @return self instance for chaining.
+     */
+    default T setBootstrapRoot(String path) {
+        return amend(BOOTSTRAP_ROOT_OPTION, path);
+    }
+
+    /**
+     * Get the full path to WebDriverAgentMac root folder where Xcode project
+     * of the server sources lives.
+     *
+     * @return The full path to WebDriverAgentMac root folder.
+     */
+    default Optional<String> getBootstrapRoot() {
+        return Optional.ofNullable((String) getCapability(BOOTSTRAP_ROOT_OPTION));
+    }
+}

src/main/java/io/appium/java_client/mac/options/SupportsBundleIdOption.java

@@ -0,0 +1,53 @@
+/*
+ * 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.mac.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 SupportsBundleIdOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String BUNDLE_ID_OPTION = "bundleId";
+
+    /**
+     * The bundle identifier of the application to automate, for example
+     * com.apple.TextEdit. This is an optional capability. If it is not provided
+     * then the session will be started without an application under test
+     * (actually, it will be Finder). If the application with the given
+     * identifier is not installed then an error will be thrown on session
+     * startup. If the application is already running then it will be moved to
+     * the foreground.
+     *
+     * @param identifier A valid application bundle identifier.
+     * @return self instance for chaining.
+     */
+    default T setBundleId(String identifier) {
+        return amend(BUNDLE_ID_OPTION, identifier);
+    }
+
+    /**
+     * Get the bundle identifier of the application to automate.
+     *
+     * @return Application bundle identifier.
+     */
+    default Optional<String> getBundleId() {
+        return Optional.ofNullable((String) getCapability(BUNDLE_ID_OPTION));
+    }
+}

src/main/java/io/appium/java_client/mac/options/SupportsEnvironmentOption.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.mac.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.List;
+import java.util.Optional;
+
+public interface SupportsEnvironmentOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String ENVIRONMENT_OPTION = "environment";
+
+    /**
+     * A dictionary of environment variables (name-&gt;value) that are going to be passed
+     * to the application under test on top of environment variables inherited from
+     * the parent process. This capability is only going to be applied if the application
+     * is not running on session startup.
+     *
+     * @param arguments E.g. ["--help"].
+     * @return self instance for chaining.
+     */
+    default T setEnvironment(List<String> arguments) {
+        return amend(ENVIRONMENT_OPTION, arguments);
+    }
+
+    /**
+     * Get the application environment variables mapping.
+     *
+     * @return Application environment mapping.
+     */
+    default Optional<List<String>> getEnvironment() {
+        //noinspection unchecked
+        return Optional.ofNullable((List<String>) getCapability(ENVIRONMENT_OPTION));
+    }
+}

src/main/java/io/appium/java_client/mac/options/SupportsPostrunOption.java

@@ -0,0 +1,54 @@
+/*
+ * 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.mac.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.Map;
+import java.util.Optional;
+
+public interface SupportsPostrunOption<T extends BaseOptions<T>> extends
+        Capabilities, CanSetCapability<T> {
+    String POSTRUN_OPTION = "postrun";
+
+    /**
+     * An object containing either script or command key. The value of
+     * each key must be a valid AppleScript script or command to be
+     * executed after Mac2Driver session is stopped. See
+     * https://github.com/appium/appium-mac2-driver#applescript-commands-execution
+     * for more details.
+     *
+     * @param script A valid AppleScript snippet.
+     * @return self instance for chaining.
+     */
+    default T setPostrun(RunScript script) {
+        return amend(POSTRUN_OPTION, script.toMap());
+    }
+
+    /**
+     * Get the postrun script.
+     *
+     * @return Postrun script.
+     */
+    default Optional<RunScript> getPostrun() {
+        //noinspection unchecked
+        return Optional.ofNullable(getCapability(POSTRUN_OPTION))
+                .map((v) -> new RunScript((Map<String, Object>) v));
+    }
+}