Merge branch 'master' into tvos-ios17-workaround2

CHANGELOG.md

@@ -1,3 +1,10 @@
+## [7.8.0](https://github.com/appium/appium-xcuitest-driver/compare/v7.7.2...v7.8.0) (2024-03-28)
+
+
+### Features
+
+* Add 'appLaunchStateTimeoutSec' capability support ([#2371](https://github.com/appium/appium-xcuitest-driver/issues/2371)) ([c0514e4](https://github.com/appium/appium-xcuitest-driver/commit/c0514e4050c7ab19d3e83a0026a81fa83e8218c4))
+
 ## [7.7.2](https://github.com/appium/appium-xcuitest-driver/compare/v7.7.1...v7.7.2) (2024-03-28)
 
 

docs/preparation/real-device-config.md

@@ -86,3 +86,15 @@ Since iOS 16, Apple requires a device to have a live internet connection for val
 signing. It is possible to set up an offline enabled provisiong profile, which allows you to avoid
 the limitation. Please read [this issue](https://github.com/appium/appium/issues/18378#issuecomment-1482678074)
 regarding detailed configuration steps.
+
+## Tune WebDriverAgent to improve session startup performance
+
+Running `xcodebuild` every time takes much longer time to complete a session startup.
+XCUITest driver offers a few methods to improve the performance with, or without using `xcodebuild`.
+
+Some might require deeper understanding of iOS development environment,
+but they help to improve speedup your test execution speed.
+
+- [Run Preinstalled WebDriverAgentRunner](./../guides/run-preinstalled-wda.md)
+- [Run Prebuilt WebDriverAgentRunner](./../guides/run-prebuilt-wda.md)
+- [Attach to a Running WebDriverAgent](./../guides/attach-to-running-wda.md)

docs/reference/capabilities.md

@@ -86,6 +86,7 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 |`appium:forceAppLaunch`| Specify if the app should be forcefully restarted if it is already running on session startup. This capability only has an effect if an application identifier has been passed to the test session (either explicitly, by setting bundleId, or implicitly, by providing app). Default is `true` unless `noReset` capability is set to `true`. |`true` or `false`|
 |`appium:useNativeCachingStrategy`| Set this capability to `false` in order to use the custom elements caching strategy. This might help to avoid stale element exception on property change. By default the native XCTest cache resolution is used (`true`) for all native locators (e.g. all, but xpath). Check the corresponding [WebDriverAgent pull request](https://github.com/appium/WebDriverAgent/pull/516) for more details. |`true` or `false`|
 |`appium:skipDeviceCheck`| _Experimental. This capability may be removed without major version update if we no longer need this._ Whether to skip the device check in a new session request. This capability, `"appium:webDriverAgentUrl": "<device ip address>:<WDA port>"` and `"appium:skipLogCapture": true` might help to avoid [Apple TV 4k tvOS 17](https://github.com/appium/appium/issues/19343) connection issue, but if you need this capability, the session would have communication issue with the device. Commands that can work over WebDriverAgent may work, but commands such as application installation may not work. (We do not recommend using this capability. Please use this only when you need this.) Default is `false`. | `true` or `false` |
+|`appium:appLaunchStateTimeoutSec`|Allows to set the timeout in float seconds for the application state change on the session startup in range (0, 240) exclusively. The default value for it in XCTest is 60 seconds, which means WDA would throw an exception if the application under test is not ready for accessibility interactions in 60s after its process has started. **Important**: The fact the application's user interface is visible does not necessarily mean it could be immediately interacted with by XCTest. The latter must ensure the app's main thread is also idling. Setting this capability to a lower value might help to avoid prolonged test startup with problematic apps taking too much time to be ready and fail fast. It is not advised to increase the capability value above 60 seconds, rather consider fixing the affected application itself. Too low values though may cause unexpected app startup failures. The capability does not have an effect if the app under test is not (re)started at the beginning of the session. | `10.5` |
 
 ### Simulator
 

lib/desired-caps.js

@@ -367,9 +367,12 @@ const desiredCapConstraints = /** @type {const} */ ({
   forceSimulatorSoftwareKeyboardPresence: {
     isBoolean: true,
   },
+  appLaunchStateTimeoutSec: {
+    isNumber: true,
+  },
   skipDeviceCheck: {
     isBoolean: true,
-  },
+  }
 });
 
 export {desiredCapConstraints, PLATFORM_NAME_IOS, PLATFORM_NAME_TVOS};

lib/driver.js

@@ -1359,6 +1359,7 @@ export class XCUITestDriver extends BaseDriver {
       disableAutomaticScreenshots: this.opts.disableAutomaticScreenshots,
       shouldTerminateApp: this.opts.shouldTerminateApp ?? true,
       forceAppLaunch: this.opts.forceAppLaunch ?? true,
+      appLaunchStateTimeoutSec: this.opts.appLaunchStateTimeoutSec,
       useNativeCachingStrategy: this.opts.useNativeCachingStrategy ?? true,
       forceSimulatorSoftwareKeyboardPresence:
         this.opts.forceSimulatorSoftwareKeyboardPresence ??

package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "7.7.2",
+  "version": "7.8.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -81,7 +81,7 @@
     "appium-ios-device": "^2.5.4",
     "appium-ios-simulator": "^6.1.2",
     "appium-remote-debugger": "^11.0.0",
-    "appium-webdriveragent": "^8.1.0",
+    "appium-webdriveragent": "^8.2.1",
     "appium-xcode": "^5.1.4",
     "async-lock": "^1.4.0",
     "asyncbox": "^3.0.0",

test/unit/language-specs.js

@@ -23,6 +23,7 @@ describe('language and locale', function () {
     useNativeCachingStrategy: true,
     shouldUseSingletonTestManager: true,
     eventloopIdleDelaySec: 0,
+    appLaunchStateTimeoutSec: undefined,
     environment: {},
   };
 

test/unit/processargs-specs.js

@@ -22,6 +22,7 @@ describe('process args', function () {
     useNativeCachingStrategy: true,
     shouldTerminateApp: true,
     shouldUseSingletonTestManager: true,
+    appLaunchStateTimeoutSec: undefined,
     eventloopIdleDelaySec: 0,
   };