feat: let usePrebuiltWDA run prebuild when the given derivedDataPath has no directories, or no this.wda.retrieveDerivedDataPath present

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`
 

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"` |

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();