feat: Document respectSystemAlerts setting (#2402)

docs/guides/troubleshooting.md

@@ -21,11 +21,16 @@ System dialogs, such as permission dialogs, might not be interactable directly w
 Despite a similar look, dialogs belonging to the active session application (e.g. initially passed as `appium:app` or `appium:bundleId` capability value)
 do not require such adjustment.
 
-XCUITest driver offers a few methods to handle them.
-
-- Start a session without `appium:app` nor `appium:bundleId`. Then XCUITest driver attempts to get the current active application. This requires you to start an application after a new session request with [`mobile: installApp`](../reference/execute-methods.md#mobile-installapp) to install an app if needed and [`mobile: launchApp`](../reference/execute-methods.md#mobile-launchapp)/[`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp), but it could automatically change the active application with `com.apple.springboard` or activated application on the top. (Note that the automatic detection could have a delay, thus each action could take more time.)
-    - When a permission alert exists on the top, it could select the `com.apple.springboard`
-    - When another application is on the top by accepting/denying the system alert, or [`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp), the application would be selected as an active application.
+XCUITest driver offers a couple of approaches to handle them:
+
+- Set the [respectSystemAlerts setting](../reference/settings.md) to `true`. It enforces the active application
+  detection algorithm to check a presence of system alerts and to return the Springboard app if this check succeeds.
+  Such approach emulates the driver behavior prior to version 6 of XCUITest driver, although it might slightly
+  slow down your scripts because each attempt to detect an active app would require to also query for alerts
+  presence.
+- Start a session without `appium:app` nor `appium:bundleId`. Then XCUITest driver attempts to get the current active application. This requires you to start an application after a new session request with [`mobile: installApp`](../reference/execute-methods.md#mobile-installapp) to install an app if needed and [`mobile: launchApp`](../reference/execute-methods.md#mobile-launchapp)/[`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp), but it could automatically change the active application with `com.apple.springboard` or activate an application at the foreground. (Note that the automatic app detection might be lengthy, thus each action could take more time.)
+    - When a permission alert exists at the foreground, it could select the `com.apple.springboard`
+    - When another application is at the foreground by accepting/denying the system alert, or [`mobile: activateApp`](../reference/execute-methods.md#mobile-activateapp), the application would be selected as an active application.
 - [`mobile: alert`](../reference/execute-methods.md#mobile-alert)
 - `defaultActiveApplication` setting in [Settings](../reference/settings.md).
     - e.g. With the [Appium Ruby client](https://github.com/appium/ruby_lib_core)

docs/reference/settings.md

@@ -39,3 +39,4 @@ Along with the common settings, the following driver-specific settings are avail
 | `useJSONSource` | `boolean` | See the description of the corresponding capability. |
 | `pageSourceExcludedAttributes` | `string` | One or more comma-separated attribute names to be excluded from the XML output. It might be sometimes helpful to exclude, for example, the `visible` attribute, to significantly speed-up page source retrieval. This does not affect the XML output when `useJSONSource` is enabled. Defaults to an empty string. Example: `"visible,accessible"` |
 | `maxTypingFrequency` | `int` | Maximum frequency of keystrokes for typing and clear. If your tests are failing because of typing errors, you may want to adjust this. Defaults to `60` keystrokes per minute. |
+| `respectSystemAlerts` | `boolean` | Currently we detect the app under test as active if XCTest returns XCUIApplicationStateRunningForeground state for it. In case the app under test is covered by a system alert from the Springboard app this approach might be confusing as we cannot interact with it unless an alert is properly handled. If this setting is set to true (by default it is false) then it forces WDA to verify the presence of alerts shown by Springboard and return the latter while performing the automated app detection. It affects the performance of active app detection, but might be more convenient for writing test scripts (e.g. eliminates the need of proactive switching between system and custom apps). Also, this behavior emulates the legacy active application detection logic before version 6 of the driver. |

package.json

@@ -81,7 +81,7 @@
     "appium-ios-device": "^2.5.4",
     "appium-ios-simulator": "^6.1.2",
     "appium-remote-debugger": "^11.1.0",
-    "appium-webdriveragent": "^8.6.0",
+    "appium-webdriveragent": "^8.7.0",
     "appium-xcode": "^5.1.4",
     "async-lock": "^1.4.0",
     "asyncbox": "^3.0.0",