The Settings API · Appium 官方文檔

## Settings Settings是appium引入的一個新概念。它們目前不是 Mobile JSON Wire 協議或 Webdriver 規范的一部分。 Settings是用來指定appium server的工作方式。 Settings有以下特點: - 可變性，Settings在一個會話中是可以被修改的。 - 臨時性，Settings只對當前會話生效，新建立的會話會被重置。 - 局限性，Settings只用來控制appium server，不能用于控制被測應用或設備。以Android的 `ignoreUnimportantViews` 為例。Android中可以設置 `ignoreUnimportantViews` 用來忽略所有與當前視圖無關的元素，這樣可以讓用例執行的更快。注意，當用戶需要訪問這些被忽略的元素時，需要禁用 `ignoreUnimportantViews` 后并重新啟用。另外一個例子是Settings讓appium忽略當前不可見的元素。 Settings通過下面的API實現： ### [Update Device Settings](../commands/session/settings/update-settings.md) **POST** /session/:sessionId/appium/settings >Settings使用鍵值對(name:value)的JSON格式，name為setting的名字，value是setting的取值。 ``` { settings: { ignoreUnimportantViews : true } } ``` ### [Retrieve Device Settings](../commands/session/settings/get-settings.md) **GET** /session/:sessionId/appium/settings >返回當前指定 settings 的 JSON ``` { ignoreUnimportantViews : true } ``` ## 支持的 Settings |名稱|描述|值| |----|----|----| |`shouldUseCompactResponses`|查找element/elements，返回簡潔(標準兼容)、快速的響應結果。默認為`true`|`false`或`true`| |`elementResponseAttributes`|為每個元素返回逗號分隔的字段列表，僅`shouldUseCompactResponses`為`false`時生效。iOS默認值為"type，label"，Android默認值為""|例如，`"name，text，rect，attribute/name，attribute/value"`| [圖像元素](https://github.com/appium/appium/blob/master../advanced-concepts/image-elements.md)也有圖像元素的特定settings。 ### 僅 Android 支持 |名稱|描述|值| |----|----|----| |`ignoreUnimportantViews`|設置為false時，Android設備不會忽略任何views；被設置為true時，會使用setCompressedLayoutHeirarchy()忽略標記了IMPORTANT_FOR_ACCESSIBILITY_NO或IMPORTANT_FOR_ACCESSIBILITY_AUTO（以及被系統認為不重要的）的views，從而盡量讓腳本變得簡單或執行的更快。默認值為`false`|`false`或`true`| #### UiAutomator2 |名稱|描述|值| |----|----|----| |`actionAcknowledgmentTimeout`|與[setActionAcknowledgmentTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setActionAcknowledgmentTimeout(long))相同。被設置為負數時將取默認值(3*1000 毫秒)。Android API 18及以上版本，由 [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) 處理。|例如，`5000`| |`allowInvisibleElements`|控制安卓設備是否顯示所有可見或不可見的元素。默認值為false|`false`或`true`| |`enableMultiWindows`|值為true時，page source和xpath會查找所有可訪問窗口，而不僅是當前的一個窗口。可以解決查找類似`android.widget.PopupWindow`窗口上的元素，默認值為`false`，只返回當前窗口。查閱 [appium-uiautomator2-server#301](https://github.com/appium/appium-uiautomator2-server/pull/301) 獲取更多信息。|`true`或`false`| |`enableNotificationListener`|控制安卓設備是否開啟或關閉`NotificationListener`，默認值為`true`。|`false`或`true`| |`keyInjectionDelay`|與:[setKeyInjectionDelay](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setKeyInjectionDelay(long))相同。被設置為負數時將取默認值(0 毫秒)。Android API 18及以上版本，由 [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) 處理。|例如，`5000`| |`mjpegBilinearFiltering`|控制是否在源截圖縮放算法里應用線性過濾。開啟后會提升縮放后的位圖質量，但可能產生[很小]的性能影響。默認值為`false`。|`false`或`true`| |`mjpegScalingFactor`|控制截屏流的比例因子。100代表沒有進行縮放（如原圖大小的100%），圖尺寸越大，編譯時就需要消耗更多CPU性能。Int類型，取值范圍為`1`到`100`，默認值為`50`|`1`到`100`| |`mjpegServerFramerate`|控制截屏流的幀率。幀率越高，CPU負載越大，幀率最大值受限于待測設備的性能。Int類型，取值范圍為`1`到`60`。默認值為`10`|`1`到`60`| |`mjpegServerPort`|控制 MJPEG 服務端口號。Int類型，取值范圍為`1024`and`65535`，默認值為`7810`。|`1024`到`65535`| |`mjpegServerScreenshotQuality`|控制截屏流的質量。100代表質量最佳，1代表質量最差。bitmap轉為JPEG格式時，值越大，編譯時越需要消耗更多CPU時間。通常設置為25到90就可以，值太大特別影響性能，還不能帶來可見的質量提升。值太小也會導致結果圖出現明顯的扭曲。Int類型，值范圍為`1`and`100`，默認值為`50`|`1`到`100`| |`normalizeTagNames`|將作為 XML tags 的所有 class names，轉化為由 Apache Harmony庫支持的ASCII字符的子集。Android默認使用，以避免由于 XPath 查找導致的XML解析異常。轉化基于[junidecode](https://github.com/gcardone/junidecode)，需要避免 [這個問題](https://github.com/appium/appium/issues/11854)，默認值為`false`。|`false`或`true`| |`scrollAcknowledgmentTimeout`|與:[setScrollAcknowledgmentTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setScrollAcknowledgmentTimeout(long))相同。被設置為負數時將取默認值(200 毫秒)。Android API 18及以上版本，由 [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) 處理。|例如`300`| |`serverPort`|控制服務端端口號，Int類型，取值范圍為`1024`and`65535`，默認值為`6790`。|`1024`到`65535`| |`shutdownOnPowerDisconnect`|監聽到電源斷開[ACTION_POWER_DISCONNECTED](https://developer.android.com/reference/android/content/Intent.html#ACTION_POWER_DISCONNECTED)的系統廣播后關閉服務。默認值為`true`。|`false`或`true`| |`simpleBoundsCalculation`|值為`true`時，會計算`bounds`屬性，這個方法雖然不太準確，但簡單還能提升性能，Appium 1.18.0 版本開始支持，默認值為`false`|`false`或`true`| |`trackScrollEvents`|跟蹤scroll事件，值為`true`時，會把`lastScrollData`字段加到`getSession`的結果里，這樣就能用于監控 scroll 進度，值為`false`時會顯著提升 touch 操作的性能，默認值為`true`。|`false`或`true`| |`waitForIdleTimeout`|與:[setWaitForIdleTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setWaitForIdleTimeout(long))相同。被設置為負數時將取默認值(10*1000 毫秒)。Android API 18及以上版本，由 [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) 處理。|例如`10000`| |`waitForSelectorTimeout`|與:[setWaitForSelectorTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setWaitForSelectorTimeout(long))相同。被設置為負數時將取默認值(10*1000 毫秒)。Android API 18及以上版本，由 [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) 處理。|例如`10000`| |`wakeLockTimeout`|獲取喚醒鎖（wake lock）超時時間。服務啟動時獲取并持有喚醒鎖（wake lock），直到 UIAutomator2 服務被殺掉或者超時。喚醒鎖（wake lock）被持有時，如果設置值為0或負數，將會立即被釋放。默認值為'24*60*60*1000' 毫秒。|例如`0`，`60000`(1 min)| ### 僅 iOS 支持 #### XCUITest |名稱|描述|值|Appium支持的版本| |----|----|----|----| |`nativeWebTap`|啟用后，可以在 Safari 里點擊 non-javascript-based 頁面。默認值為`false`，提醒：依賴 viewport 的大小/比例，點擊元素時可能不太準確。|`true`，`false`|1.7.0+| |`mjpegServerScreenshotQuality`|截圖廣播生成的截圖質量，取值范圍`0`to`100`。值為`0`代表壓縮最多（質量最差），值為`100`代表壓縮最少（質量最佳）。默認值為`25`|例如，`10`|1.10.0+| |`mjpegServerFramerate`|值為`1..60`之間時，后臺截圖廣播，播報截圖的幀率，默認值為`10`(每秒幀數)。值設置為0時，幀率會取可達到的最大值。|例如，`60`|1.10.0+| |`screenshotQuality`|參考[xctest/xctimagequality](https://developer.apple.com/documentation/xctest/xctimagequality?language=objc)修改手機屏幕截圖的質量，默認值是`1`。參閱 [appium-xcuitest-driver](https://github.com/appium/appium-xcuitest-driver#desired-capabilities)里的`screenshotQuality`capabilities|例如`0`，`1`，`2`|1.10.0+| |`mjpegScalingFactor`|修改截屏的比例，默認值為`100`，無縮放。Int類型，取值范圍為`1`and`100`。|例如`1`，`50`，`100`|1.12.0+| |`keyboardAutocorrection`|鍵盤設置里修改自動校正設置，當 WDA 基于 xctest 啟動時，默認值為`false`。|`true`，`false`|1.14.0+| |`keyboardPrediction`|鍵盤設置里修改預測設置，當 WDA 基于 xctest 啟動時，默認值為`false`。|`true`，`false`|1.14.0+| |`snapshotTimeout`|修改獲取快照(snapshots)的過期時長。_Snapshots_主要用于生成page source，查找 XML 以及檢索屬性。當page source非常大，包含幾百個UI元素時，需要增加 snapshotTimeout 的值。默認值為15秒。|例如`10`，`100`(秒)|1.15.0+| |`snapshotMaxDepth`|修改遍歷元素source tree的最大深度值，這個設置在獲取元素source tree時有助于防止內存不足或超時，但同時也限制了source tree的深度。當在Appium log里看到這樣的報錯，如 _Timed out snapshotting com.apple.testmanagerd..._ message 或 _Cannot get 'xml' source of the current application_，需要考慮限制 snapshotMaxDepth 的值，因為這類問題很可能和超時有關。如果 snapshotMaxDepth 值特別小，可能會丟失元素 source tree 的部分內容。默認值為`50`|例如`100`|1.17.0+| |`useFirstMatch`|開啟這個設置后，查找單個元素速度會變快，但查找嵌套元素時會有[問題](https://github.com/appium/appium/issues/10101)。默認值是`false`|`true`，`false`|1.15.0+| |`reduceMotion`|在輔助功能里修改減弱動態效果(motion)。|`true`，`false`|1.15.0+| |`defaultActiveApplication`|設置當前可選程序。有助于 WebDriverAgent 從多項可選程序列表里，選擇當前程序。這個設置在分屏APP自動化上很有用，默認值為`auto`，這樣 WebDriverAgent 可以選擇元素位于`screenPoint`的應用，或者從當前 apps 列表里（并且列表里只有一個app）選擇其中一個應用。|例如，`com.apple.Preferences`|1.15.0+| |`activeAppDetectionPoint`|設置當前屏幕上的坐標點，如當前屏幕上有多個應用，WebDriverAgent 可以使用坐標點檢測當前應用。值的格式是`x，y`，只有 x 和 y 值為float類型或者Int類型時，才是有效屏幕坐標。設置超出屏幕坐標的的值，可能會導致 WebDriverAgent 報錯。默認的屏幕坐標值，分別為最小屏幕尺寸的20%，即`MIN(w，h) * 0.2，MIN(w，h) * 0.2`|例如`100，300`|1.15.0+| |`includeNonModalElements`|iOS 13+ 設備上，是否返回所有帶對話框的元素。這個設置解決了這個問題[cannot find elements on nested modal presentations](https://github.com/appium/appium/issues/13227)，但也會導致可見屬性不可靠。為了提升元素可見監測，還要開啟`shouldUseTestManagerForVisibilityDetection`設置(默認值是`false`)或`simpleIsVisibleCheck`capability。這個問題會在 iOS 13.0到13.2(以及 Xcode 11.0到11.2)上出現。這個查詢會導致以下問題，在更新的 iOS/Xcode 版本上，includeNonModalElements 返回 nil，以及 Appium/WDA 在未使用此設置時，會返回3個相同的元素。默認值為`false`|`true`，`false`|1.15.0+| |`acceptAlertButtonSelector`|允許自定義 accept 警告按鈕 selector。這樣就能處理任意元素，就像在`accept alert`命令里處理 accept 按鈕那樣。selector 必須是個有效的[class chain](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules) 表達式，查詢路徑必須是 alert 元素自身。如果給定的 selector 錯誤或者無法匹配任何元素，默認會使用按鈕定位算法。|例如，<code>**/XCUIElementTypeButton[\`label CONTAINS[c] 'accept'\`]</code>|1.16.0+| |`dismissAlertButtonSelector`|允許自定義 dismiss 警告按鈕 selector。這樣就能處理任意元素，就像在`dismiss alert`命令里處理 dismiss 按鈕那樣。selector 必須是個有效的[class chain](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules) 表達式，查詢路徑必須是 alert 元素自身。如果給定的 selector 錯誤或者無法匹配任何元素，默認會使用按鈕定位算法。|例如，<code>**/XCUIElementTypeButton[\`label CONTAINS[c] 'dismiss'\`]</code>|1.16.0+| |`screenshotOrientation`|在 iOS 上調整截屏方向，Appium 嘗試返回截圖，同時使用內部方法調整截圖方向，但有時候并不生效（尤其是橫屏時）。實際截屏方向受多個因素影響，如 OS 版本，model 版本，以及當前設備是真機還是模擬器。這個設置允許強制設置圖片方向，默認值是`auto`|`auto`，`portrait`，`portraitUpsideDown`，`landscapeRight`，`landscapeLeft`|1.17.0+| 本文由 [nicole1010](https://github.com/nicole1010) 翻譯，由 [lihuazhang](https://github.com/lihuazhang) 校驗。