feat: Add Gecko driver options (appium#1573)

Author: mykola-mokhnach

src/main/java/io/appium/java_client/AppiumDriver.java

@@ -17,6 +17,7 @@
 package io.appium.java_client;
 
 import static io.appium.java_client.internal.CapabilityHelpers.APPIUM_PREFIX;
+import static io.appium.java_client.remote.MobileCapabilityType.AUTOMATION_NAME;
 import static io.appium.java_client.remote.MobileCapabilityType.PLATFORM_NAME;
 import static org.apache.commons.lang3.StringUtils.isBlank;
 
@@ -129,16 +130,36 @@ public AppiumDriver(Capabilities capabilities) {
  * @param originalCapabilities the given {@link Capabilities}.
  * @param defaultName a {@link MobileCapabilityType#PLATFORM_NAME} value which has
  * to be set up
- * @return {@link Capabilities} with changed mobile platform name value or the original capabilities
+ * @return {@link Capabilities} with changed platform name value or the original capabilities
  */
- protected static Capabilities ensurePlatformName(Capabilities originalCapabilities,
-   String defaultName) {
+ protected static Capabilities ensurePlatformName(
+ Capabilities originalCapabilities, String defaultName) {
  String currentName = (String) originalCapabilities.getCapability(PLATFORM_NAME);
  return isBlank(currentName)
  ? originalCapabilities.merge(new ImmutableCapabilities(PLATFORM_NAME, defaultName))
  : originalCapabilities;
  }
 
+ /**
+ * Changes automation name if it is not set and returns merged capabilities.
+ *
+ * @param originalCapabilities the given {@link Capabilities}.
+ * @param defaultName a {@link MobileCapabilityType#AUTOMATION_NAME} value which has
+ * to be set up
+ * @return {@link Capabilities} with changed mobile automation name value or the original capabilities
+ */
+ protected static Capabilities ensureAutomationName(
+ Capabilities originalCapabilities, String defaultName) {
+ String currentAutomationName = CapabilityHelpers.getCapability(
+ originalCapabilities, AUTOMATION_NAME, String.class);
+ if (isBlank(currentAutomationName)) {
+ String capabilityName = originalCapabilities.getCapabilityNames()
+ .contains(AUTOMATION_NAME) ? AUTOMATION_NAME : APPIUM_PREFIX + AUTOMATION_NAME;
+ return originalCapabilities.merge(new ImmutableCapabilities(capabilityName, defaultName));
+ }
+ return originalCapabilities;
+ }
+
  /**
  * Changes platform and automation names if they are not set
  * and returns merged capabilities.
@@ -147,27 +168,12 @@ protected static Capabilities ensurePlatformName(Capabilities originalCapabiliti
  * @param defaultPlatformName a {@link MobileCapabilityType#PLATFORM_NAME} value which has
  * to be set up
  * @param defaultAutomationName The default automation name to set up for this class
- * @return {@link Capabilities} with changed mobile platform name value or the original capabilities
+ * @return {@link Capabilities} with changed platform/automation name value or the original capabilities
  */
  protected static Capabilities ensurePlatformAndAutomationNames(
  Capabilities originalCapabilities, String defaultPlatformName, String defaultAutomationName) {
- MutableCapabilities toMerge = new MutableCapabilities();
- String currentPlatformName = (String) originalCapabilities.getCapability(PLATFORM_NAME);
- if (isBlank(currentPlatformName)) {
- toMerge.setCapability(PLATFORM_NAME, defaultPlatformName);
- }
- String currentAutomationName = CapabilityHelpers.getCapability(
- originalCapabilities, MobileCapabilityType.AUTOMATION_NAME, String.class);
- if (isBlank(currentAutomationName)) {
- toMerge.setCapability(originalCapabilities.getCapabilityNames()
- .contains(MobileCapabilityType.AUTOMATION_NAME)
- ? MobileCapabilityType.AUTOMATION_NAME
- : APPIUM_PREFIX + MobileCapabilityType.AUTOMATION_NAME,
- defaultAutomationName);
- }
- return toMerge.getCapabilityNames().isEmpty()
- ? originalCapabilities
- : originalCapabilities.merge(toMerge);
+ Capabilities capsWithPlatformFixed = ensurePlatformName(originalCapabilities, defaultPlatformName);
+ return ensureAutomationName(capsWithPlatformFixed, defaultAutomationName);
  }
 
  @Override

src/main/java/io/appium/java_client/gecko/GeckoDriver.java

@@ -0,0 +1,79 @@
+/*
+ * 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.gecko;
+
+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.remote.HttpCommandExecutor;
+import org.openqa.selenium.remote.http.HttpClient;
+
+import java.net.URL;
+
+/**
+ * GeckoDriver is an officially supported Appium driver
+ * created to automate Mobile browsers and web views based on
+ * the Gecko engine. The driver uses W3C
+ * WebDriver protocol and is built on top of Mozilla's geckodriver
+ * server. Read https://github.com/appium/appium-geckodriver
+ * for more details on how to configure and use it.
+ *
+ * @since Appium 1.20.0
+ */
+public class GeckoDriver extends AppiumDriver {
+ private static final String AUTOMATION_NAME = AutomationName.GECKO;
+
+ public GeckoDriver(HttpCommandExecutor executor, Capabilities capabilities) {
+ super(executor, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(URL remoteAddress, Capabilities capabilities) {
+ super(remoteAddress, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(URL remoteAddress, HttpClient.Factory httpClientFactory, Capabilities capabilities) {
+ super(remoteAddress, httpClientFactory, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(AppiumDriverLocalService service, Capabilities capabilities) {
+ super(service, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(AppiumDriverLocalService service, HttpClient.Factory httpClientFactory,
+ Capabilities capabilities) {
+ super(service, httpClientFactory, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(AppiumServiceBuilder builder, Capabilities capabilities) {
+ super(builder, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(AppiumServiceBuilder builder, HttpClient.Factory httpClientFactory,
+ Capabilities capabilities) {
+ super(builder, httpClientFactory, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(HttpClient.Factory httpClientFactory, Capabilities capabilities) {
+ super(httpClientFactory, ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+
+ public GeckoDriver(Capabilities capabilities) {
+ super(ensureAutomationName(capabilities, AUTOMATION_NAME));
+ }
+}

src/main/java/io/appium/java_client/gecko/options/GeckoOptions.java

@@ -0,0 +1,66 @@
+/*
+ * 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.gecko.options;
+
+import io.appium.java_client.mac.options.SupportsSystemPortOption;
+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 java.util.Map;
+
+/**
+ * https://github.com/appium/appium-geckodriver#usage
+ */
+public class GeckoOptions extends BaseOptions<GeckoOptions> implements
+ SupportsBrowserNameOption<GeckoOptions>,
+ SupportsBrowserVersionOption<GeckoOptions>,
+ SupportsMarionettePortOption<GeckoOptions>,
+ SupportsSystemPortOption<GeckoOptions>,
+ SupportsVerbosityOption<GeckoOptions>,
+ SupportsAndroidStorageOption<GeckoOptions>,
+ SupportsMozFirefoxOptionsOption<GeckoOptions>,
+ SupportsAcceptInsecureCertsOption<GeckoOptions>,
+ SupportsPageLoadStrategyOption<GeckoOptions>,
+ SupportsSetWindowRectOption<GeckoOptions>,
+ SupportsProxyOption<GeckoOptions>,
+ SupportsUnhandledPromptBehaviorOption<GeckoOptions> {
+ public GeckoOptions() {
+ setCommonOptions();
+ }
+
+ public GeckoOptions(Capabilities source) {
+ super(source);
+ setCommonOptions();
+ }
+
+ public GeckoOptions(Map<String, ?> source) {
+ super(source);
+ setCommonOptions();
+ }
+
+ private void setCommonOptions() {
+ setAutomationName(AutomationName.GECKO);
+ }
+}

src/main/java/io/appium/java_client/gecko/options/SupportsAndroidStorageOption.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.gecko.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 SupportsAndroidStorageOption<T extends BaseOptions<T>> extends
+ Capabilities, CanSetCapability<T> {
+ String ANDROID_STORAGE_OPTION = "androidStorage";
+
+ /**
+ * See
+ * https://firefox-source-docs.mozilla.org/testing/geckodriver
+ * /Flags.html#code-android-storage-var-android-storage-var-code
+ *
+ * @param storage One of supported Android storage types.
+ * @return self instance for chaining.
+ */
+ default T setAndroidStorage(String storage) {
+ return amend(ANDROID_STORAGE_OPTION, storage);
+ }
+
+ /**
+ * Get the currently set storage type.
+ *
+ * @return String representing the name of the device.
+ */
+ default Optional<String> getAndroidStorage() {
+ return Optional.ofNullable((String) getCapability(ANDROID_STORAGE_OPTION));
+ }
+}

src/main/java/io/appium/java_client/gecko/options/SupportsMarionettePortOption.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.gecko.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.toInteger;
+
+public interface SupportsMarionettePortOption<T extends BaseOptions<T>> extends
+ Capabilities, CanSetCapability<T> {
+ String MARIONETTE_PORT_OPTION = "marionettePort";
+
+ /**
+ * Selects the port for Geckodriver’s connection to the Marionette
+ * remote protocol. The existing Firefox instance must have Marionette
+ * enabled. To enable the remote protocol in Firefox, you can pass the
+ * -marionette flag. Unless the marionette.port preference has been
+ * user-set, Marionette will listen on port 2828, which is the default
+ * value for this capability.
+ *
+ * @param port port number in range 0..65535
+ * @return self instance for chaining.
+ */
+ default T setMarionettePort(int port) {
+ return amend(MARIONETTE_PORT_OPTION, port);
+ }
+
+ /**
+ * Get the number of the port for the Marionette server to listen on.
+ *
+ * @return Marionette port value.
+ */
+ default Optional<Integer> getMarionettePort() {
+ return Optional.ofNullable(toInteger(getCapability(MARIONETTE_PORT_OPTION)));
+ }
+}

src/main/java/io/appium/java_client/gecko/options/SupportsMozFirefoxOptionsOption.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.gecko.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 SupportsMozFirefoxOptionsOption<T extends BaseOptions<T>> extends
+ Capabilities, CanSetCapability<T> {
+ String MOZ_FIREFOX_OPTIONS_OPTION = "moz:firefoxOptions";
+
+ /**
+ * See https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions.
+ *
+ * @param options Firefox options mapping.
+ * @return self instance for chaining.
+ */
+ default T setMozFirefoxOptions(Map<String, Object> options) {
+ return amend(MOZ_FIREFOX_OPTIONS_OPTION, options);
+ }
+
+ /**
+ * Get Firefox options mapping.
+ *
+ * @return Firefox options mapping.
+ */
+ default Optional<Map<String, Object>> getMozFirefoxOptions() {
+ //noinspection unchecked
+ return Optional.ofNullable((Map<String, Object>) getCapability(MOZ_FIREFOX_OPTIONS_OPTION));
+ }
+}