feat: tvos 17+ workaround with skipDeviceCheck

docs/reference/capabilities.md

@@ -84,6 +84,8 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 |`appium:shouldTerminateApp`| Specify if the app should be terminated on session end. 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: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`| Whether to skip the device check in a new session request. This could 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 will 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

@@ -361,6 +361,9 @@ const desiredCapConstraints = /** @type {const} */ ({
   skipSyncUiDialogTranslation: {
     isBoolean: true,
   },
+  skipDeviceCheck: {
+    isBoolean: true,
+  },
 });
 
 export {desiredCapConstraints, PLATFORM_NAME_IOS, PLATFORM_NAME_TVOS};

lib/driver.js

@@ -388,6 +388,18 @@ class XCUITestDriver extends BaseDriver {
     return !(CAP_NAMES_NO_XCODEBUILD_REQUIRED.some((x) => Boolean(this.opts[x])));
   }
 
+  /**
+   * 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 real device.
+   * A situation that requires this capability may hve an issue to communicate with the device
+   * over appium-ios-device for example.
+   * Some methods that require the appium-ios-device may get issues.
+   * @returns {boolean}
+   */
+  skipDeviceCheck() {
+    return !!this.opts.skipDeviceCheck;
+  }
+
   async createSession(w3cCaps1, w3cCaps2, w3cCaps3, driverData) {
     try {
       let [sessionId, caps] = await super.createSession(w3cCaps1, w3cCaps2, w3cCaps3, driverData);
@@ -600,14 +612,16 @@ class XCUITestDriver extends BaseDriver {
     await this.installAUT();
 
     // if we only have bundle identifier and no app, fail if it is not already installed
-    if (
-      !this.opts.app &&
-      this.opts.bundleId &&
-      !this.isSafari() &&
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      !(await this.opts.device.isAppInstalled(this.opts.bundleId))
-    ) {
-      this.log.errorAndThrow(`App with bundle identifier '${this.opts.bundleId}' unknown`);
+    if (!this.skipDeviceCheck()) {
+      if (
+        !this.opts.app &&
+        this.opts.bundleId &&
+        !this.isSafari() &&
+        // @ts-expect-error - do not assign arbitrary properties to `this.opts`
+        !(await this.opts.device.isAppInstalled(this.opts.bundleId))
+      ) {
+        this.log.errorAndThrow(`App with bundle identifier '${this.opts.bundleId}' unknown`);
+      }
     }
 
     if (this.isSimulator()) {
@@ -1207,19 +1221,23 @@ class XCUITestDriver extends BaseDriver {
           return {device, realDevice: false, udid: device.udid};
         }
       } else {
-        // make sure it is a connected device. If not, the udid passed in is invalid
-        const devices = await getConnectedDevices();
-        this.log.debug(`Available devices: ${devices.join(', ')}`);
-        if (!devices.includes(this.opts.udid)) {
-          // check for a particular simulator
-          this.log.debug(`No real device with udid '${this.opts.udid}'. Looking for a simulator`);
-          try {
-            const device = await getSimulator(this.opts.udid, {
-              devicesSetPath: this.opts.simulatorDevicesSetPath,
-            });
-            return {device, realDevice: false, udid: this.opts.udid};
-          } catch (ign) {
-            throw new Error(`Unknown device or simulator UDID: '${this.opts.udid}'`);
+        if (this.skipDeviceCheck()) {
+          this.log.info(`Skipping connected device check. Using the given udid ${this.opts.udid}.`);
+        } else {
+          // make sure it is a connected device. If not, the udid passed in is invalid
+          const devices = await getConnectedDevices();
+          this.log.debug(`Available devices: ${devices.join(', ')}`);
+          if (!devices.includes(this.opts.udid)) {
+            // check for a particular simulator
+            this.log.debug(`No real device with udid '${this.opts.udid}'. Looking for a simulator`);
+            try {
+              const device = await getSimulator(this.opts.udid, {
+                devicesSetPath: this.opts.simulatorDevicesSetPath,
+              });
+              return {device, realDevice: false, udid: this.opts.udid};
+            } catch (ign) {
+              throw new Error(`Unknown device or simulator UDID: '${this.opts.udid}'`);
+            }
           }
         }
       }
@@ -1656,6 +1674,11 @@ class XCUITestDriver extends BaseDriver {
       return;
     }
 
+    if (this.opts.bundleId && this.skipDeviceCheck()) {
+      this.log.info('Skipping the bundle id installation check');
+      return;
+    }
+
     await verifyApplicationPlatform(this.opts.app, {
       isSimulator: this.isSimulator(),
       isTvOS: isTvOs(this.opts.platformName),