Add the missing Android and iOS settings (#1120)

* Add the missing Android and iOS settings

* Tune docs

* Fix docstrings

Author: mykola-mokhnach

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

@@ -18,25 +18,37 @@
 
 /**
  * Enums defining constants for Appium Settings which can be set and toggled during a test session.
+ * http://appium.io/docs/en/advanced-concepts/settings/
  */
 public enum Setting {
 
+    // Android
     IGNORE_UNIMPORTANT_VIEWS("ignoreUnimportantViews"),
     WAIT_FOR_IDLE_TIMEOUT("waitForIdleTimeout"),
     WAIT_FOR_SELECTOR_TIMEOUT("waitForSelectorTimeout"),
     WAIT_SCROLL_ACKNOWLEDGMENT_TIMEOUT("scrollAcknowledgmentTimeout"),
     WAIT_ACTION_ACKNOWLEDGMENT_TIMEOUT("actionAcknowledgmentTimeout"),
+    ALLOW_INVISIBLE_ELEMENTS("allowInvisibleElements"),
+    ENABLE_NOTIFICATION_LISTENER("enableNotificationListener"),
+    NORMALIZE_TAG_NAMES("normalizeTagNames"),
     KEY_INJECTION_DELAY("keyInjectionDelay"),
+    // iOS
+    MJPEG_SERVER_SCREENSHOT_QUALITY("mjpegServerScreenshotQuality"),
+    MJPEG_SERVER_FRAMERATE("mjpegServerFramerate"),
+    SCREENSHOT_QUALITY("screenshotQuality"),
     NATIVE_WEB_TAP("nativeWebTap"),
+    // Android and iOS
+    SHOULD_USE_COMPACT_RESPONSES("shouldUseCompactResponses"),
+    ELEMENT_RESPONSE_ATTRIBUTES("elementResponseAttributes"),
+    // All platforms
+    IMAGE_ELEMENT_TAP_STRATEGY("imageElementTapStrategy"),
     IMAGE_MATCH_THRESHOLD("imageMatchThreshold"),
     FIX_IMAGE_FIND_SCREENSHOT_DIMENSIONS("fixImageFindScreenshotDims"),
     FIX_IMAGE_TEMPLATE_SIZE("fixImageTemplateSize"),
     CHECK_IMAGE_ELEMENT_STALENESS("checkForImageElementStaleness"),
-    UPDATE_IMAGE_ELEMENT_POSITION("autoUpdateImageElementPosition"),
-    NORMALIZE_TAG_NAMES("normalizeTagNames"),
-    IMAGE_ELEMENT_TAP_STRATEGY("imageElementTapStrategy");
+    UPDATE_IMAGE_ELEMENT_POSITION("autoUpdateImageElementPosition");
 
-    private String name;
+    private final String name;
 
     Setting(String name) {
         this.name = name;

src/main/java/io/appium/java_client/android/HasAndroidSettings.java

@@ -30,59 +30,71 @@ interface HasAndroidSettings extends HasSettings {
      * by the system), in an attempt to make things less confusing or faster.
      *
      * @param compress ignores unimportant views if true, doesn't ignore otherwise.
+     * @return self instance for chaining
      */
-    default void ignoreUnimportantViews(Boolean compress) {
+    default HasAndroidSettings ignoreUnimportantViews(Boolean compress) {
         setSetting(Setting.IGNORE_UNIMPORTANT_VIEWS, compress);
+        return this;
     }
 
     /**
      * invoke {@code setWaitForIdleTimeout} in {@code com.android.uiautomator.core.Configurator}.
      *
      * @param timeout A negative value would reset to its default value. Minimum time unit
      *                resolution is one millisecond
+     * @return self instance for chaining
      */
-    default void configuratorSetWaitForIdleTimeout(Duration timeout) {
+    default HasAndroidSettings configuratorSetWaitForIdleTimeout(Duration timeout) {
         setSetting(Setting.WAIT_FOR_IDLE_TIMEOUT, timeout.toMillis());
+        return this;
     }
 
     /**
      * invoke {@code setWaitForSelectorTimeout} in {@code com.android.uiautomator.core.Configurator}.
      *
      * @param timeout A negative value would reset to its default value. Minimum time unit
      *                resolution is one millisecond
+     * @return self instance for chaining
      */
-    default void configuratorSetWaitForSelectorTimeout(Duration timeout) {
+    default HasAndroidSettings configuratorSetWaitForSelectorTimeout(Duration timeout) {
         setSetting(Setting.WAIT_FOR_SELECTOR_TIMEOUT, timeout.toMillis());
+        return this;
     }
 
     /**
      * invoke {@code setScrollAcknowledgmentTimeout} in {@code com.android.uiautomator.core.Configurator}.
      *
      * @param timeout A negative value would reset to its default value. Minimum time unit
      *                resolution is one millisecond
+     * @return self instance for chaining
      */
-    default void configuratorSetScrollAcknowledgmentTimeout(Duration timeout) {
+    default HasAndroidSettings configuratorSetScrollAcknowledgmentTimeout(Duration timeout) {
         setSetting(Setting.WAIT_SCROLL_ACKNOWLEDGMENT_TIMEOUT, timeout.toMillis());
+        return this;
     }
 
     /**
      * invoke {@code configuratorSetKeyInjectionDelay} in {@code com.android.uiautomator.core.Configurator}.
      *
      * @param delay A negative value would reset to its default value. Minimum time unit
      *              resolution is one millisecond
+     * @return self instance for chaining
      */
-    default void configuratorSetKeyInjectionDelay(Duration delay) {
+    default HasAndroidSettings configuratorSetKeyInjectionDelay(Duration delay) {
         setSetting(Setting.KEY_INJECTION_DELAY, delay.toMillis());
+        return this;
     }
 
     /**
      * invoke {@code setActionAcknowledgmentTimeout} in {@code com.android.uiautomator.core.Configurator}.
      *
      * @param timeout A negative value would reset to its default value. Minimum time unit
      *                resolution is one millisecond
+     * @return self instance for chaining
      */
-    default void configuratorSetActionAcknowledgmentTimeout(Duration timeout) {
+    default HasAndroidSettings configuratorSetActionAcknowledgmentTimeout(Duration timeout) {
         setSetting(Setting.WAIT_ACTION_ACKNOWLEDGMENT_TIMEOUT, timeout.toMillis());
+        return this;
     }
 
     /**
@@ -93,10 +105,64 @@ default void configuratorSetActionAcknowledgmentTimeout(Duration timeout) {
      * XML parsing exceptions caused by XPath lookup.
      * The Unicode to ASCII transliteration is based on
      * JUnidecode library (https://github.com/gcardone/junidecode).
+     * Works for UIAutomator2 only.
      *
      * @param enabled Either true or false. The default value if false.
+     * @return self instance for chaining
      */
-    default void normalizeTagNames(boolean enabled) {
+    default HasAndroidSettings normalizeTagNames(boolean enabled) {
         setSetting(Setting.NORMALIZE_TAG_NAMES, enabled);
+        return this;
+    }
+
+    /**
+     * Whether to return compact (standards-compliant) and faster responses in find element/s
+     * (the default setting). If set to false then the response may also contain other
+     * available element attributes.
+     *
+     * @param enabled Either true or false. The default value if true.
+     * @return self instance for chaining
+     */
+    default HasAndroidSettings setShouldUseCompactResponses(boolean enabled) {
+        setSetting(Setting.SHOULD_USE_COMPACT_RESPONSES, enabled);
+        return this;
+    }
+
+    /**
+     * Which attributes should be returned if compact responses are disabled.
+     * It works only if shouldUseCompactResponses is false. Defaults to "type,label" string.
+     *
+     * @param attrNames The comma-separated list of fields to return with each element.
+     * @return self instance for chaining
+     */
+    default HasAndroidSettings setElementResponseAttributes(String attrNames) {
+        setSetting(Setting.ELEMENT_RESPONSE_ATTRIBUTES, attrNames);
+        return this;
+    }
+
+    /**
+     * Set whether the source output/xpath search should consider all elements, visible and invisible.
+     * Disabling this setting speeds up source and xml search. Works for UIAutomator2 only.
+     *
+     * @param enabled Either true or false. The default value if false.
+     * @return self instance for chaining
+     */
+    default HasAndroidSettings allowInvisibleElements(boolean enabled) {
+        setSetting(Setting.ALLOW_INVISIBLE_ELEMENTS, enabled);
+        return this;
+    }
+
+    /**
+     * Whether to enable or disable the notification listener.
+     * No toast notifications are going to be added into page source output if
+     * this setting is disabled.
+     * Works for UIAutomator2 only.
+     *
+     * @param enabled Either true or false. The default value if true.
+     * @return self instance for chaining
+     */
+    default HasAndroidSettings enableNotificationListener(boolean enabled) {
+        setSetting(Setting.ENABLE_NOTIFICATION_LISTENER, enabled);
+        return this;
     }
 }

src/main/java/io/appium/java_client/ios/HasIOSSettings.java

@@ -22,10 +22,77 @@
 interface HasIOSSettings extends HasSettings {
     /**
      * Set the `nativeWebTap` setting. *iOS-only method*.
-     * Sets whether Safari/webviews should convert element taps into x/y taps
+     * Sets whether Safari/webviews should convert element taps into x/y taps.
+     *
      * @param enabled turns nativeWebTap on if true, off if false
+     * @return self instance for chaining
      */
-    default void nativeWebTap(Boolean enabled) {
+    default HasIOSSettings nativeWebTap(Boolean enabled) {
         setSetting(Setting.NATIVE_WEB_TAP, enabled);
+        return this;
+    }
+
+    /**
+     * Whether to return compact (standards-compliant) and faster responses from find element/s
+     * (the default setting). If set to false then the response may also contain other
+     * available element attributes.
+     *
+     * @param enabled Either true or false. The default value if true.
+     * @return self instance for chaining
+     */
+    default HasIOSSettings setShouldUseCompactResponses(boolean enabled) {
+        setSetting(Setting.SHOULD_USE_COMPACT_RESPONSES, enabled);
+        return this;
+    }
+
+    /**
+     * Which attributes should be returned if compact responses are disabled.
+     * It works only if shouldUseCompactResponses is set to false. Defaults to an empty string.
+     *
+     * @param attrNames The comma-separated list of fields to return with each element.
+     * @return self instance for chaining
+     */
+    default HasIOSSettings setElementResponseAttributes(String attrNames) {
+        setSetting(Setting.ELEMENT_RESPONSE_ATTRIBUTES, attrNames);
+        return this;
+    }
+
+    /**
+     * The quality of the screenshots generated by the screenshots broadcaster,
+     * The value of 0 represents the maximum compression
+     * (or lowest quality) while the value of 100 represents the least compression (or best quality).
+     *
+     * @param quality An integer in range 0..100. The default value is 25.
+     * @return self instance for chaining
+     */
+    default HasIOSSettings setMjpegServerScreenshotQuality(int quality) {
+        setSetting(Setting.MJPEG_SERVER_SCREENSHOT_QUALITY, quality);
+        return this;
+    }
+
+    /**
+     * The frame rate at which the background screenshots broadcaster should broadcast screenshots in range 1..60.
+     * The default value is 10 (Frames Per Second).
+     * Setting zero value will cause the frame rate to be at its maximum possible value.
+     *
+     * @param framerate An integer in range 1..60. The default value is 10.
+     * @return self instance for chaining
+     */
+    default HasIOSSettings setMjpegServerFramerate(int framerate) {
+        setSetting(Setting.MJPEG_SERVER_FRAMERATE, framerate);
+        return this;
+    }
+
+    /**
+     * Changes the quality of phone display screenshots according to XCTest/XCTImageQuality enum.
+     * Sometimes setting this value to the maximum possible quality may crash XCTest because of
+     * lack of the memory (lossless screenshot require more space).
+     *
+     * @param quality An integer in range 0..2. The default value is 1.
+     * @return self instance for chaining
+     */
+    default HasIOSSettings setScreenshotQuality(int quality) {
+        setSetting(Setting.SCREENSHOT_QUALITY, quality);
+        return this;
     }
 }