feat: tvos 17 workaround with skipDeviceCheck

docs/reference/capabilities.md

@@ -89,6 +89,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: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` |
+|`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` |
 
 ### Simulator
 

lib/desired-caps.js

@@ -383,7 +383,10 @@ const desiredCapConstraints = /** @type {const} */ ({
   pageLoadStrategy: {
     isString: true,
     inclusionCaseInsensitive: ['none', 'eager', 'normal']
-  }
+  },
+  skipDeviceCheck: {
+    isBoolean: true,
+  },
 });
 
 export {desiredCapConstraints, PLATFORM_NAME_IOS, PLATFORM_NAME_TVOS};

lib/driver.js

@@ -255,6 +255,9 @@ export class XCUITestDriver extends BaseDriver {
   /** @type {import('./commands/pcap').TrafficCapture|null} */
   _trafficCapture;
 
+  /** @type {boolean} */
+  skipDeviceCheck;
+
   /** @type {Simulator|RealDevice} */
   _device;
 
@@ -323,6 +326,13 @@ export class XCUITestDriver extends BaseDriver {
     this.appInfosCache = new AppInfosCache(this.log);
     this.remote = null;
     this.doesSupportBidi = true;
+
+    // Whether to skip the device check in a new session request.
+    // This is a workaround for network-connected devices such as an Apple TV 4k tvOS 17+ real device.
+    // A situation that requires this capability may have an issue with communicating with the device
+    // over appium-ios-device for example.
+    // Please remove this capability when we no longer need this workaround.
+    this.skipDeviceCheck = this.opts.skipDeviceCheck || false;
   }
 
   async onSettingsUpdate(key, value) {
@@ -621,14 +631,16 @@ export class XCUITestDriver extends BaseDriver {
 
     await this.installAUT();
 
-    // if we only have bundle identifier and no app, fail if it is not already installed
-    if (
+    // if we only have bundle identifier and no app, fail if it is not already installed.
+    if (this.skipDeviceCheck) {
+      this.log.debug(`Skipping ${this.opts.bundleId} installation check since skipDeviceCheck was given.`);
+    } else if (
       !this.opts.app &&
       this.opts.bundleId &&
       !this.isSafari() &&
       !(await this.device.isAppInstalled(this.opts.bundleId))
     ) {
-      this.log.errorAndThrow(`App with bundle identifier '${this.opts.bundleId}' unknown`);
+      throw this.log.errorWithException(`App with bundle identifier '${this.opts.bundleId}' unknown`);
     }
 
     if (this.isSimulator()) {
@@ -1582,6 +1594,11 @@ export class XCUITestDriver extends BaseDriver {
       return;
     }
 
+    if (this.opts.bundleId && this.skipDeviceCheck) {
+      this.log.debug('Skipping the bundle id installation check');
+      return;
+    }
+
     await verifyApplicationPlatform.bind(this)();
 
     const {install, skipUninstall} = await this.checkAutInstallationState();