Merge branch 'master' into webview-retry-with-reconnect

CHANGELOG.md

@@ -1,3 +1,74 @@
+## [7.11.1](https://github.com/appium/appium-xcuitest-driver/compare/v7.11.0...v7.11.1) (2024-04-08)
+
+
+### Bug Fixes
+
+* update real device check condition ([9255e7c](https://github.com/appium/appium-xcuitest-driver/commit/9255e7c932d20967b0c7860df14015c5b4a63d15))
+
+## [7.11.0](https://github.com/appium/appium-xcuitest-driver/compare/v7.10.0...v7.11.0) (2024-04-08)
+
+
+### Features
+
+* export doctor used in xcuitest driver ([#2381](https://github.com/appium/appium-xcuitest-driver/issues/2381)) ([e8fd02e](https://github.com/appium/appium-xcuitest-driver/commit/e8fd02e00dc6be595d2bef253c00ab75783504e5))
+
+## [7.10.0](https://github.com/appium/appium-xcuitest-driver/compare/v7.9.3...v7.10.0) (2024-04-08)
+
+
+### Features
+
+* Add `appTimeZone` capability ([#2379](https://github.com/appium/appium-xcuitest-driver/issues/2379)) ([a06931f](https://github.com/appium/appium-xcuitest-driver/commit/a06931fca03ef4f3de0ea65eb7814660dcb08117))
+
+## [7.9.3](https://github.com/appium/appium-xcuitest-driver/compare/v7.9.2...v7.9.3) (2024-04-07)
+
+
+### Bug Fixes
+
+* Added platformVersion to capabilities ([#2378](https://github.com/appium/appium-xcuitest-driver/issues/2378)) ([e75cd2c](https://github.com/appium/appium-xcuitest-driver/commit/e75cd2c127b0b2d1206cbd4d7b22923ee553798c))
+* Update various type declarations ([#2380](https://github.com/appium/appium-xcuitest-driver/issues/2380)) ([1e18b2f](https://github.com/appium/appium-xcuitest-driver/commit/1e18b2f7c859f915aa353716add65d0a404c0fa7))
+
+## [7.9.2](https://github.com/appium/appium-xcuitest-driver/compare/v7.9.1...v7.9.2) (2024-04-07)
+
+
+### Bug Fixes
+
+* Properly match simulator udid if webDriverAgentUrl is provided ([#2377](https://github.com/appium/appium-xcuitest-driver/issues/2377)) ([bc71415](https://github.com/appium/appium-xcuitest-driver/commit/bc7141569f6148a8de77dc1989c2400a10a6c3f8))
+
+## [7.9.1](https://github.com/appium/appium-xcuitest-driver/compare/v7.9.0...v7.9.1) (2024-03-31)
+
+
+### Miscellaneous Chores
+
+* bump wda ([a777b93](https://github.com/appium/appium-xcuitest-driver/commit/a777b93a5953dfd59e54f40817d198307f72289f))
+
+## [7.9.0](https://github.com/appium/appium-xcuitest-driver/compare/v7.8.2...v7.9.0) (2024-03-31)
+
+
+### Features
+
+* Enable Safari settings modification for real devices ([#2373](https://github.com/appium/appium-xcuitest-driver/issues/2373)) ([2bf1dc5](https://github.com/appium/appium-xcuitest-driver/commit/2bf1dc56d80ec712c6a7691ca24192df6fc6f4eb))
+
+## [7.8.2](https://github.com/appium/appium-xcuitest-driver/compare/v7.8.1...v7.8.2) (2024-03-29)
+
+
+### Miscellaneous Chores
+
+* bump WDA ([1c3d68b](https://github.com/appium/appium-xcuitest-driver/commit/1c3d68b13a60513b4da9179351831ab05ca14bf3))
+
+## [7.8.1](https://github.com/appium/appium-xcuitest-driver/compare/v7.8.0...v7.8.1) (2024-03-29)
+
+
+### Miscellaneous Chores
+
+* left a comment for future work ([#2372](https://github.com/appium/appium-xcuitest-driver/issues/2372)) ([3f13c62](https://github.com/appium/appium-xcuitest-driver/commit/3f13c624ab2c89c8ff89dd07b2fdcaf33f5d5265))
+
+## [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/guides/run-prebuilt-wda.md

@@ -55,7 +55,7 @@ xcodebuild test-without-building \
   provided `.xctestrun` file. Once this is done, `http://localhost:8100` will be able to receive
   commands for the target device.
 
-## Capabilities for Prebuilt WDA with `appium:useXctestrunFile`
+## Capabilities for Prebuilt WDA with `appium:useXctestrunFile`, `appium:usePrebuiltWDA` or `appium:prebuildWDA`
 
 The XCUITest driver provides two capabilities that allow skipping the `build-for-testing` command,
 and executing only the `test-without-building` command: __`appium:useXctestrunFile`__ and
@@ -85,10 +85,15 @@ The capabilities can be used as follows:
 
 Not all combinations have been tested, but the target device can probably be anything.
 
-The same thing can be achieved with the `appium:derivedDataPath` and `appium:usePrebuiltWDA`
+The same thing can be achieved with the __`appium:derivedDataPath`__ and __`appium:usePrebuiltWDA`__
 capabilities, but this may fail if `xcodebuild` cannot find or handle the `.xctestrun` file
 properly. The stability depends on Xcode.
 
+__`appium:prebuildWDA`__ lets the XCUITest driver build the WDA before running it, then the session
+will be handled with `appium:usePrebuiltWDA`.
+It might have additional building steps than with `appium:derivedDataPath` and `appium:usePrebuiltWDA`
+combination, but it could help `appium:usePrebuiltWDA` to not manage the WDA project.
+
 ## Capabilities for Prebuilt WDA with `appium:prebuiltWDAPath`
 
 [Run Preinstalled WebDriverAgentRunner](./run-prebuilt-wda.md) provides `appium:prebuiltWDAPath` capability.

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

@@ -37,6 +37,7 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 | `appium:calendarFormat` | Calendar format to set for iOS Simulator, for example `gregorian` or `persian`. Can only be set in conjunction with `appium:locale`. |
 | `appium:appPushTimeout` | The timeout for application upload in milliseconds. Works for real devices only. The default value is `30000`ms |
 | `appium:appInstallStrategy` | Select application installation strategy for real devices. The following strategies are supported:<br>`serial` (default) - pushes app files to the device in a sequential order; this is the least performant strategy, although the most reliable<br>`parallel` - pushes app files simultaneously; this is usually the the most performant strategy, but sometimes could not be very stable<br>`ios-deploy` - tells the driver to use a third-party tool [ios-deploy](https://www.npmjs.com/package/ios-deploy) to install the app; obviously the tool must be installed separately first and must be present in PATH before it could be used. |
+| `appium:appTimeZone` | Defines the custom time zone override for the application under test. You can use UTC, PST, EST, as well as place-based timezone names such as America/Los_Angeles. The application must be (re)launched for the capability to take effect. See the [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for more details. The same behavior could be achieved by providing a custom value to the [TZ](https://developer.apple.com/forums/thread/86951#263395) environment variable via the `appium:processArguments` capability | UTC |
 
 ### WebDriverAgent
 
@@ -60,7 +61,8 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 |`appium:wdaBaseUrl`| This value if specified, will be used as a prefix to build a custom `WebDriverAgent` url. It is different from `webDriverAgentUrl`, because if the latter is set then it expects `WebDriverAgent` to be already listening and skips the building phase. Defaults to `http://localhost` | `http://192.168.1.100`|
 |`appium:showXcodeLog`|Whether to display the output of the Xcode command used to run the tests. If this is `true`, there will be **lots** of extra logging at startup. Defaults to `false`|`true`|
 |`appium:iosInstallPause`|Time in milliseconds to pause between installing the application and starting `WebDriverAgent` on the device. Used particularly for larger applications. Defaults to `0`|`8000`|
-|`appium:usePrebuiltWDA`|Skips the build phase of running the WDA app. Building is then the responsibility of the user. Only works for Xcode 8+. Defaults to `false`.|`true`|
+|`appium:prebuildWDA`|Enables prebuilding if the WebDriverAgentRunner application before running the WDA app. With this capability, XCUITest driver builds the WDA project first, then it handles the session as `appium:usePrebuiltWDA` `true` behavior. Defaults to `false`.|`true`|
+|`appium:usePrebuiltWDA`|Skips the build phase of running the WDA app. Building is then the responsibility of the user. `appium:derivedDataPath` let the session use the path as `-derivedDataPath` argument for `xcodebuild` command. Defaults to `false`.|`true`|
 |`appium:prebuiltWDAPath`| The full path to the prebuilt WebDriverAgent-Runner application package to be installed if `appium:usePreinstalledWDA` capability is enabled. The package's bundle identifier could be customized via `appium:updatedWDABundleId` capability. |`/path/to/WebDriverAgentRunner-Runner.app`|
 |`appium:usePreinstalledWDA`| Whether to launch a preinstalled WebDriverAgentRunner application using a custom XCTest API client (via `com.apple.instruments` service) instead of running `xcodebuild` for real devices or simulators via simctl tool (since driver version 7.4.0). If `appium:prebuiltWDAPath` is provided, XCUITest driver will install WebDriverAgent-Runner app from the given path before launching the application. The preinstalled WebDriverAgent package must be built by Xcode 12+. The default target bundle identifier is `com.facebook.WebDriverAgentRunner.xctrunner`, although it could be customized by providing the `appium:updatedWDABundleId` capability value (the `.xctrunner` suffix is added automatically). Please read [Run Preinstalled WebDriverAgentRunner](../guides/run-preinstalled-wda.md) for more details. Defaults to `false`. |`true` or `false`|
 |`appium:updatedWDABundleIdSuffix`| Add suffix for the bundle id provided by the `appium:updatedWDABundleId` capability value in `appium:usePreinstalledWDA` capability usage since XCUITest driver v7.6.0. This is for an advanced usage that sets an arbitrary `CFBundleIdentifier` for prebuilt WebDriverAgent package to sign with the bundle identifier's certificate. For example, if you would need to sign a WebDriverAgent package with `io.appium.wda` bundle identifier's certificate, the WebDriverAgent's package must have the same bundle identifier as `CFBundleIdentifier`. Then, the WebDriverAgent package can be launched by `io.appium.wda`, which does not have `.xctrunner`. Then `"appium:updatedWDABundleIdSuffix": ""` (an empty string) helps.  Please read [Run Preinstalled WebDriverAgentRunner](../guides/run-preinstalled-wda.md) for more details. Defaults to `.xctrunner`. | `""`, `".customsuffix"` |
@@ -85,6 +87,7 @@ 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: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
 
@@ -112,7 +115,7 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 |`appium:simulatorPasteboardAutomaticSync`| Handle the `-PasteboardAutomaticSync` flag when simulator process launches. It could improve launching simulator performance not to sync pasteboard with the system when this value is `off`. `on` forces the flag enabled. `system` does not provide the flag to the launching command. `on`, `off`, or `system` is available. They are case insensitive. Defaults to `off` | `system` |
 |`appium:simulatorDevicesSetPath`| This capability allows to set an alternative path to the simulator devices set in case you have multiple sets deployed on your local system. Such feature could be useful if you, for example, would like to save disk space on the main system volume. | `/MyVolume/Devices` |
 |`appium:webkitResponseTimeout`| (Real device only) Set the time, in ms, to wait for a response from WebKit in a Safari session. Defaults to `5000` | `10000`|
-|`appium:safariGlobalPreferences`| Allows changing of Mobile Safari's preferences at the session startup. Check the documentation on arguments of [mobile: updateSafariPreferences](./execute-methods.md#mobile-updatesafaripreferences) extension to get more details on the value type requirements. | `{ ShowTabBar: 0, WarnAboutFraudulentWebsites: 0 }` |
+|`appium:safariGlobalPreferences`| Allows changing of Mobile Safari's preferences at the session startup. Check the documentation on arguments of [mobile: updateSafariPreferences](./execute-methods.md#mobile-updatesafaripreferences) extension to get more details on the value type requirements. Only available on real devices since driver version 7.9.0. A new Safari instance must be launched upon test startup for this capability to take effect on real devices. | `{ ShowTabBar: 0, WarnAboutFraudulentWebsites: 0 }` |
 
 ### Web Context
 
@@ -132,9 +135,9 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 |`appium:nativeWebTap`| Enable native, non-javascript-based taps being in web context mode. Defaults to `false`. Warning: sometimes the preciseness of native taps could be broken, because there is no reliable way to map web element coordinates to native ones. | `true` |
 |`appium:nativeWebTapStrict`| Enabling this capability would skip the additional logic that tries to match web view elements to native ones by using their textual descriptions. Depending on the actual web view content this algorithm might sometimes be not very reliable and will slow down each click as we anyway fallback to the usual coordinates transformation flow if it fails. It is advised to enable strict tap if you use [mobile: calibrateWebToRealCoordinatesTranslation](./execute-methods.md#mobile-calibratewebtorealcoordinatestranslation) extension. Only applicable if `nativeWebTap` is enabled. `false` by default | `true` |
 |`appium:safariInitialUrl`| Initial safari url, default is a local welcome page. Setting it to an empty string will skip the initial navigation. | `https://www.github.com` |
-|`appium:safariAllowPopups`| (Simulator only) Allow javascript to open new windows in Safari. Default keeps current sim setting. |`true` or `false`|
-|`appium:safariIgnoreFraudWarning`| (Simulator only) Prevent Safari from showing a fraudulent website warning. Default keeps current sim setting. |`true` or `false`|
-|`appium:safariOpenLinksInBackground`| (Simulator only) Whether Safari should allow links to open in new windows. Default keeps current sim setting. |`true` or `false`|
+|`appium:safariAllowPopups`| Allow javascript to open new windows in Safari. Default keeps the current setting. Only available on real devices since driver version 7.9.0. A new Safari instance must be launched upon test startup on real devices for this capability to take effect. |`true` or `false`|
+|`appium:safariIgnoreFraudWarning`| Prevent Safari from showing a fraudulent website warning. Default keeps the current setting. Only available on real devices since driver version 7.9.0. A new Safari instance must be launched upon test startup on real devices for this capability to take effect. |`true` or `false`|
+|`appium:safariOpenLinksInBackground`| Whether Safari should allow links to open in new windows. Default keeps the current sim setting. Only available on real devices since driver version 7.9.0. A new Safari instance must be launched upon test startup on real devices for this capability to take effect. |`true` or `false`|
 |`appium:webviewConnectRetries`| Number of times to send connection message to remote debugger, to get webview. Default: `8` |`12`|
 |`appium:webkitResponseTimeout`| (Real device only) Set the time, in ms, to wait for a response from WebKit in a Safari session. Defaults to `5000`|`10000`|
 |`appium:enableAsyncExecuteFromHttps`| Capability to allow simulators to execute asynchronous JavaScript on pages using HTTPS. Defaults to `false` | `true` or `false` |

index.js

@@ -1,4 +1,7 @@
 import {XCUITestDriver} from './lib/driver';
 
 export {XCUITestDriver};
+
+export * as doctor from './lib/doctor/checks';
+
 export default XCUITestDriver;

lib/app-utils.js

@@ -14,6 +14,15 @@ export const APP_EXT = '.app';
 export const IPA_EXT = '.ipa';
 /** @type {LRUCache<string, import('@appium/types').StringRecord>} */
 const PLIST_CACHE = new LRUCache({max: 20});
+const SAFARI_OPTS_ALIASES_MAP = /** @type {const} */ ({
+  safariAllowPopups: [
+    ['WebKitJavaScriptCanOpenWindowsAutomatically', 'JavaScriptCanOpenWindowsAutomatically'],
+    (x) => Number(Boolean(x)),
+  ],
+  safariIgnoreFraudWarning: [['WarnAboutFraudulentWebsites'], (x) => Number(!x)],
+  safariOpenLinksInBackground: [['OpenLinksInBackground'], (x) => Number(Boolean(x))],
+});
+
 
 /**
  * Retrieves the value of the given entry name from the application's Info.plist.
@@ -288,3 +297,24 @@ export async function isolateAppBundle(appRoot) {
   await fs.mv(appRoot, dstRoot, {mkdirp: true});
   return dstRoot;
 }
+
+/**
+ * Builds Safari preferences object based on the given session capabilities
+ *
+ * @param {import('./driver').XCUITestDriverOpts} opts
+ * @return {Promise<import('@appium/types').StringRecord>}
+ */
+export function buildSafariPreferences(opts) {
+  const safariSettings = _.cloneDeep(opts?.safariGlobalPreferences ?? {});
+
+  for (const [name, [aliases, valueConverter]] of _.toPairs(SAFARI_OPTS_ALIASES_MAP)) {
+    if (!_.has(opts, name)) {
+      continue;
+    }
+
+    for (const alias of aliases) {
+      safariSettings[alias] = valueConverter(opts[name]);
+    }
+  }
+  return safariSettings;
+}