appium-xcuitest-driver 4.12.0 → 4.12.1

package/README.md

@@ -5,14 +5,17 @@
 
 [![Release](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml/badge.svg)](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml)
 
-Appium XCUITest Driver is a combined solution, which allows to perform automated black-box testing of iOS and tvOS native applications and WebKit web views.
+Appium XCUITest Driver is a combined solution, which allows performing automated black-box testing of iOS and tvOS native applications and WebKit web views.
 The native testing is based on Apple's [XCTest](https://developer.apple.com/documentation/xctest) framework and the fork of Facebook's [WebDriverAgent](https://github.com/appium/WebDriverAgent) server (the [original](https://github.com/facebookarchive/WebDriverAgent) project is not supported anymore).
 Web views communication is done via [Webkit remote debugger protocol](https://github.com/appium/appium-remote-debugger). Real devices communication is ensured by [appium-ios-device](https://github.com/appium/appium-ios-device) library.
 Simulators communication is ensured by [appium-ios-simulator](https://github.com/appium/appium-ios-simulator) library.
 
 In the native mode the driver operates in scope of [WebDriver W3C protocol](https://w3c.github.io/webdriver) with several platform-specific extensions. Web views communication only supports the obsolete [JWP protocol](https://webdriver.io/docs/api/jsonwp.html).
 
-*Note*: Issue tracking for this repo has been disabled. Please use the [main Appium issue tracker](https://github.com/appium/appium/issues) instead.
+> **Note**
+>
+> Since version 4.0.0 XCUITest driver has dropped the support of Appium 1, and is only compatible to Appium 2.
+> Use the `appium driver install xcuitest` command to add it to your Appium 2 dist.
 
 
 ## Requirements
@@ -20,27 +23,45 @@ In the native mode the driver operates in scope of [WebDriver W3C protocol](http
 On top of standard Appium requirements XCUITest driver also expects the following prerequisites:
 
 - Only macOS is supported as the host platform
-- Xcode and developer tools must be installed. Note, that usually some time is needed for the Appium team to pick up with the support of the most recent Xcode versions, especially beta ones.
+- Xcode and developer tools must be installed. Note, that usually some time is needed for the Appium team to pick up with the support of the most recent Xcode versions, especially beta ones (check [Xcode version support](#xcode-version-support) section below).
 - Connected real devices must be trusted, added to your developer profile and configured properly along with WebDriverAgent signing. Read [Real devices](#real-devices) section _carefully_ to set them up properly before running your tests.
     - Starting from iOS/iPadOS version iOS/iPadOS 16 real devices require enabling of _Developer Mode_ option in _Settings -> Privacy & Security_
-- The minimum supported Xcode SDK version for the current driver snapshot is *10.2 (iOS 12.2)*. Consider using earlier releases of the driver (see [Xcode version support](#xcode-version-support) section below) if it is necessary to test older iOS versions on real devices. Also, it is highly recommended to always use the same major version of Xcode SDK, which was used to build the particular iOS/tvOS version on your real device under test (for example Xcode 11 for iOS 13, Xcode 12 for iOS 14, etc).
+- Consider using earlier releases of the driver (check [Xcode version support](#xcode-version-support) section below) if it is necessary to test iOS versions older than the current iOS major version minus one on real devices. Also, it is highly recommended to always use the same major version of Xcode SDK, which was used to build the particular iOS/tvOS version on your real device under test (for example Xcode 11 for iOS 13, Xcode 12 for iOS 14, etc).
 - Web views must be debuggable in order to test them. If it is not possible to connect to your web view(s) using [Safari remote debugger](https://appletoolbox.com/use-web-inspector-debug-mobile-safari/) then XCUITest won't be able to connect to them as well.
 - Since version 3.33.0 (included into Appium 1.20.0+) of XCUITest driver the [Carthage](https://github.com/Carthage/Carthage) dependency *is not needed anymore*. Prior to that version it was required and could be installed using [brew](https://brew.sh/): `brew install carthage`.
 
+
 ## Optional dependencies
 
 - [xcpretty](https://github.com/supermarin/xcpretty) tool could be used to make Xcode output easier to read. It could be installed using `gem install xcpretty` command.
 - For test video recording we use [ffmpeg](https://ffmpeg.org/). It could be installed using [brew](https://brew.sh/): `brew install ffmpeg`
 - [IDB](https://github.com/facebook/idb), [go-ios](https://github.com/danielpaulus/go-ios) and [tidevice](https://github.com/alibaba/taobao-iphone-device) could be used to improve some real device/Simulator interactions
 - [WIX AppleSimulatorUtils](https://github.com/wix/AppleSimulatorUtils) could be used to improve some Simulator interactions
+- [py-ios-device](https://github.com/YueChen-C/py-ios-device) is required in several `mobile:` extensions and to improve the general testing experience for _real_ iOS devices
 
 
 ## Xcode version support
 
-* module versions below `2.96.0` only supports XCode 8 and newer
-* module version `2.96.0` and above only supports XCode 9 and newer
-* module version `3.0.0` and above only supports Xcode 10 and newer
-* module version `3.32.0` and above only supports Xcode 10.2 and newer
+Apple constantly works on various updates/improvements to XCTest framework. Thus, some major and even minor iOS releases might partially break the backward compatibility, so we need to implement multiple branches to support the legacy and the current implementations in [WebDriverAgent](https://github.com/appium/WebDriverAgent). Eventually we just drop the support of legacy XCTest implementations in order to simplify the client code and to have access to the recent platform features. The general aim is to support the _current major_ platform version and the _previous major_ one.
+
+Minimum XCUITest driver version | Minimum required Xcode version
+--- | ---
+2.96.0 | Xcode 9
+3.0.0 | Xcode 10
+3.32.0 | Xcode 10.2
+3.56.0 | Xcode 11
+4.2.0 | Xcode 12
+
+It could be that after a new Xcode SDK is released we figure out a part or even the whole functionality that [WebDriverAgent](https://github.com/appium/WebDriverAgent) currently provides does not work anymore and needs to be updated. The below table contains the driver versions mapping for the cases where we had known compatibility issues with newly released SDKs and addressed them. Basically, version numbers in this table mean that all XCUITest driver versions _below_ the one in the first column _won't support_ Xcode SDK equal or above the version in the second column and the only way to make your test working after Xcode update would be to also *bump the driver version*.
+
+Minimum XCUITest driver version | Tested for compatibility with Xcode version
+--- | ---
+4.7.4 | Xcode 14-beta.3
+
+
+## tvOS Support
+
+Read the [tvOS support](docs/ios/ios-tvos.md) article to get more details on how to automate testing for this platform.
 
 
 ## Real devices
@@ -54,7 +75,7 @@ See [real device configuration documentation](docs/real-device-config.md).
 - After many failures on real devices it could transition to a state where connections are no longer being accepted. To possibly remedy this issue reboot the device. Read https://github.com/facebook/WebDriverAgent/issues/507 for more details.
 - iPhone/iPad real devices show overlay, which has `Automation Running Hold both volume buttons to stop` text, since iOS/iPadOS 15. This is a known limitation of XCTest framework. This limitation does not affect screenshooting APIs though (e.g. the overlay is not visible on taken screenshots).
 - iPhone/iPad real devices [require passcode or touch id](https://github.com/appium/appium/issues/15898#issuecomment-927340411) when they start a XCTest session since iOS/iPadOS 15. Disabling passcode/touch id in the device preference allows to workaround the behaviour above.
-- OpenSSL v3 breaks secured communication with real devices. It can cause a [Failed to receive any data within the timeout](https://github.com/appium/appium/issues/16399) error in [appium-ios-device](https://github.com/appium/appium-ios-device). Please read [this issue](https://github.com/appium/appium-ios-device/pull/88#discussion_r825315862) for more details.
+- OpenSSL v3 breaks secure communication with real devices. It can cause a [Failed to receive any data within the timeout](https://github.com/appium/appium/issues/16399) error in [appium-ios-device](https://github.com/appium/appium-ios-device). Please read [this issue](https://github.com/appium/appium-ios-device/pull/88#discussion_r825315862) for more details.
     - Please make sure your environment has Open SSL v1 for NodeJS environment, or prepare an OpenSSL v3 build by patching `OPENSSL_TLS_SECURITY_LEVEL=1`. (e.g. [an article](https://www.feistyduck.com/library/openssl-cookbook/online/ch-openssl.html))
     - This configuration is only necessary for XCUITest driver v4.3.0 or lower.
 
@@ -98,7 +119,7 @@ Usage: `appium --driver-args='{"xcuitest": {[argName]: [argValue]}}'`
 
 |Argument|Default|Description|Example|
 |----|-------|-----------|-------|
-|`"wdaLocalPort"`|8100| Local port used for communication with ios-web-driver-agent|`--driver-args='{"xcuitest": {"wdaLocalPort": 8100}}'`|
+| wdaLocalPort | 8100 | Local port used for communication with ios-web-driver-agent | `--driver-args='{"xcuitest": {"wdaLocalPort": 8100}}'` |
 
 ## Capabilities
 
@@ -248,7 +269,7 @@ XCUITest driver supports the following element attributes:
 Name | Description | Example
 --- | --- | ---
 name | Could contain either element's [identifier](https://developer.apple.com/documentation/xctest/xcuielementattributes/1500981-identifier?language=objc) or its [label](https://developer.apple.com/documentation/xctest/xcuielementattributes/1500692-label?language=objc), depending on which one is available first. Could also be `null`. It is recommended to prefer the usage of [accessibilityIdentifier](https://developer.apple.com/documentation/uikit/uiaccessibilityidentification/1623132-accessibilityidentifier) over [accessibilityLabel](https://developer.apple.com/documentation/objectivec/nsobject/1615181-accessibilitylabel) for automation purposes, since the `identifier` property is supposed to stay constant under different locales and does not affect accessibility services such as VoiceOver. | 'hello'
-label | Element's [label](https://developer.apple.com/documentation/xctest/xcuielementattributes/1500692-label?language=objc) value. Could be `null` | 'hello'
+label | Element's [label](https://developer.apple.com/documentation/xctest/xcuielementattributes/1500692-label?language=objc) value. Could be `null`. Since XCUITest driver 4.7.3 (WebDriverAgent 4.8.0), the behavior of this value was better aligned with XCTest, so it could include line breaks (`\n`). Before this version, line breaks were replaced by spaces. | 'hello', 'hello\nworld'
 type | Element's [type](https://developer.apple.com/documentation/xctest/xcuielementattributes/1500614-elementtype?language=objc) name | 'XCUIElementTypeButton'
 visible | Whether the element is visible. This value is not available in the "vanilla" XCTest and is read directly from the accessibility layer | 'false'
 focused | Whether the element is [focused](https://developer.apple.com/documentation/xctest/xcuielementattributes/1627636-hasfocus?language=objc). *Only available for tvOS* | 'true'

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "4.12.0",
+  "version": "4.12.1",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "4.12.0",
+      "version": "4.12.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@babel/runtime": "^7.0.0",
@@ -43,7 +43,7 @@
         "@babel/preset-env": "^7.18.10",
         "@babel/register": "^7.18.9",
         "@semantic-release/git": "^10.0.1",
-        "axios": "^0.x",
+        "axios": "^1.x",
         "babel-plugin-source-map-support": "^2.2.0",
         "chai": "^4.1.2",
         "chai-as-promised": "^7.1.1",
@@ -109,6 +109,15 @@
         "npm": ">=8"
       }
     },
+    "node_modules/@appium/base-driver/node_modules/axios": {
+      "version": "0.27.2",
+      "extraneous": true,
+      "license": "MIT",
+      "dependencies": {
+        "follow-redirects": "^1.14.9",
+        "form-data": "^4.0.0"
+      }
+    },
     "node_modules/@appium/base-plugin": {
       "version": "1.10.3",
       "extraneous": true,
@@ -236,6 +245,37 @@
         "npm": ">=8"
       }
     },
+    "node_modules/@appium/support/node_modules/axios": {
+      "version": "0.27.2",
+      "license": "MIT",
+      "dependencies": {
+        "follow-redirects": "^1.14.9",
+        "form-data": "^4.0.0"
+      }
+    },
+    "node_modules/@appium/support/node_modules/lru-cache": {
+      "version": "6.0.0",
+      "license": "ISC",
+      "dependencies": {
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/@appium/support/node_modules/semver": {
+      "version": "7.3.7",
+      "license": "ISC",
+      "dependencies": {
+        "lru-cache": "^6.0.0"
+      },
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/@appium/support/node_modules/teen_process": {
       "version": "1.16.0",
       "engines": [
@@ -992,7 +1032,7 @@
       }
     },
     "node_modules/@types/node": {
-      "version": "18.7.23",
+      "version": "18.8.2",
       "license": "MIT"
     },
     "node_modules/@types/normalize-package-data": {
@@ -1290,6 +1330,14 @@
         "appium": "^2.0.0-beta.40"
       }
     },
+    "node_modules/appium-webdriveragent/node_modules/axios": {
+      "version": "0.27.2",
+      "license": "MIT",
+      "dependencies": {
+        "follow-redirects": "^1.14.9",
+        "form-data": "^4.0.0"
+      }
+    },
     "node_modules/appium-xcode": {
       "version": "4.0.2",
       "license": "Apache-2.0",
@@ -1432,14 +1480,6 @@
       "version": "0.4.0",
       "license": "MIT"
     },
-    "node_modules/axios": {
-      "version": "0.27.2",
-      "license": "MIT",
-      "dependencies": {
-        "follow-redirects": "^1.14.9",
-        "form-data": "^4.0.0"
-      }
-    },
     "node_modules/balanced-match": {
       "version": "1.0.2",
       "license": "MIT"
@@ -3335,7 +3375,7 @@
       }
     },
     "node_modules/marked": {
-      "version": "4.1.0",
+      "version": "4.1.1",
       "extraneous": true,
       "license": "MIT",
       "bin": {
@@ -4330,7 +4370,7 @@
       "license": "ISC"
     },
     "node_modules/semver": {
-      "version": "7.3.7",
+      "version": "7.3.8",
       "license": "ISC",
       "dependencies": {
         "lru-cache": "^6.0.0"
@@ -5188,6 +5228,16 @@
         "source-map-support": "0.5.21",
         "type-fest": "2.19.0",
         "validate.js": "0.13.1"
+      },
+      "dependencies": {
+        "axios": {
+          "version": "0.27.2",
+          "extraneous": true,
+          "requires": {
+            "follow-redirects": "^1.14.9",
+            "form-data": "^4.0.0"
+          }
+        }
       }
     },
     "@appium/base-plugin": {
@@ -5295,6 +5345,25 @@
         "yauzl": "2.10.0"
       },
       "dependencies": {
+        "axios": {
+          "version": "0.27.2",
+          "requires": {
+            "follow-redirects": "^1.14.9",
+            "form-data": "^4.0.0"
+          }
+        },
+        "lru-cache": {
+          "version": "6.0.0",
+          "requires": {
+            "yallist": "^4.0.0"
+          }
+        },
+        "semver": {
+          "version": "7.3.7",
+          "requires": {
+            "lru-cache": "^6.0.0"
+          }
+        },
         "teen_process": {
           "version": "1.16.0",
           "requires": {
@@ -5817,7 +5886,7 @@
       }
     },
     "@types/node": {
-      "version": "18.7.23"
+      "version": "18.8.2"
     },
     "@types/normalize-package-data": {
       "version": "2.4.1"
@@ -6019,6 +6088,15 @@
         "node-simctl": "^7.0.1",
         "source-map-support": "^0.x",
         "teen_process": "^2.0.0"
+      },
+      "dependencies": {
+        "axios": {
+          "version": "0.27.2",
+          "requires": {
+            "follow-redirects": "^1.14.9",
+            "form-data": "^4.0.0"
+          }
+        }
       }
     },
     "appium-xcode": {
@@ -6129,13 +6207,6 @@
     "asynckit": {
       "version": "0.4.0"
     },
-    "axios": {
-      "version": "0.27.2",
-      "requires": {
-        "follow-redirects": "^1.14.9",
-        "form-data": "^4.0.0"
-      }
-    },
     "balanced-match": {
       "version": "1.0.2"
     },
@@ -7350,7 +7421,7 @@
       "requires": {}
     },
     "marked": {
-      "version": "4.1.0",
+      "version": "4.1.1",
       "extraneous": true
     },
     "mdurl": {
@@ -7980,7 +8051,7 @@
       "version": "1.2.4"
     },
     "semver": {
-      "version": "7.3.7",
+      "version": "7.3.8",
       "requires": {
         "lru-cache": "^6.0.0"
       },

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "4.12.0",
+  "version": "4.12.1",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -133,7 +133,7 @@
     "@babel/preset-env": "^7.18.10",
     "@babel/register": "^7.18.9",
     "@semantic-release/git": "^10.0.1",
-    "axios": "^0.x",
+    "axios": "^1.x",
     "babel-plugin-source-map-support": "^2.2.0",
     "chai": "^4.1.2",
     "chai-as-promised": "^7.1.1",