diff --git a/docs/guides/run-prebuilt-wda.md b/docs/guides/run-prebuilt-wda.md index 24b4db6bd..ad207343a 100644 --- a/docs/guides/run-prebuilt-wda.md +++ b/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` or `appium:usePrebuiltWDA` 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,9 +85,14 @@ 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` -capabilities, but this may fail if `xcodebuild` cannot find or handle the `.xctestrun` file -properly. The stability depends on Xcode. +The same thing can be achieved with the `appium:usePrebuiltWDA` capability. +`appium:derivedDataPath` will let the xcodebuild set the path as the `-derivedDataPath` argument. +If `appium:derivedDataPath` already has `Build` directory, Appium thinks the path already has prebuilt WDA project environment. +Then the `appium:usePrebuiltWDA` will just run xcodebuild with `test-without-building` command. + +The difference between `appium:useXctestrunFile` and `appium:usePrebuiltWDA` are +if let `xcodebuild` use specific `.xctestrun` file or use prebuilt entire WDA project. +Both stability depends on Xcode. ## Capabilities for Prebuilt WDA with `appium:prebuiltWDAPath` diff --git a/docs/reference/capabilities.md b/docs/reference/capabilities.md index d26dd5877..515a79801 100644 --- a/docs/reference/capabilities.md +++ b/docs/reference/capabilities.md @@ -60,7 +60,7 @@ 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:usePrebuiltWDA`|Run `build-for-testing` xcodebuild and start running the WDA app with `test-without-building`. If the WDA project already has prebuilt environment, the build itself takes only a few seconds. If `appium:derivedDataPath` is provided, the project destination will be the given path. If the given `appium:derivedDataPath` has `Build` directory, `build-for-testing` will be skipped. 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"` | diff --git a/lib/driver.js b/lib/driver.js index 1dbfb603a..3e0e6e951 100644 --- a/lib/driver.js +++ b/lib/driver.js @@ -554,6 +554,7 @@ export class XCUITestDriver extends BaseDriver { /** @type {import('appium-xcode').XcodeVersion} */ (this.xcodeVersion), { ...this.opts, + prebuildWDA: this.opts.usePrebuiltWDA, device: this.device, realDevice: this.isRealDevice(), iosSdkVersion: this._iosSdkVersion, @@ -727,7 +728,7 @@ export class XCUITestDriver extends BaseDriver { // Let multiple WDA binaries with different derived data folders be built in parallel // Concurrent WDA builds from the same source will cause xcodebuild synchronization errors let synchronizationKey = XCUITestDriver.name; - if (this.opts.useXctestrunFile || !(await this.wda.isSourceFresh())) { + if (this.opts.useXctestrunFile || this.opts.usePrebuiltWDA || !(await this.wda.isSourceFresh())) { // First-time compilation is an expensive operation, which is done faster if executed // sequentially. Xcodebuild spreads the load caused by the clang compiler to all available CPU cores const derivedDataPath = await this.wda.retrieveDerivedDataPath();