@@ -3,16 +3,17 @@ title: Run Prebuilt WebDriverAgentRunner
33---
44
55The XCUITest driver runs ` xcodebuild ` to build and install the WebDriverAgentRunner (WDA) app on the
6- target device. You can manually run a modified version of this command in order to prebuild the WDA.
6+ target device. Running the command every time could slow down new session creation.
7+ You can manually run a modified version of this command in order to prebuild the WDA.
78
8- ## How ` xcodebuild ` Works
9+ ## Understanding How ` xcodebuild ` Works
910
1011By default, ` xcodebuild ` is run with two commands: ` build-for-testing ` and ` test-without-building ` .
1112` build-for-testing ` builds a test bundle package, whereas ` test-without-building ` actually runs it.
1213
1314For instance, XCUITest driver issues an ` xcodebuild ` command like so:
1415
15- ```
16+ ``` bash
1617xcodebuild build-for-testing test-without-building \
1718 -project WebDriverAgent.xcodeproj \
1819 -derivedDataPath wda_build \
@@ -22,11 +23,11 @@ xcodebuild build-for-testing test-without-building \
2223```
2324
2425This translates to ` xcodebuild ` building ` WebDriverAgent.xcodeproj ` and running the resulting
25- package on the specified device.
26+ package on the specified device. The built package will be located in the ` wda_build ` path.
2627
2728The command can be split into ` build-for-testing ` and ` test-without-building ` parts as follows:
2829
29- ```
30+ ``` bash
3031xcodebuild build-for-testing \
3132 -project WebDriverAgent.xcodeproj \
3233 -derivedDataPath wda_build \
@@ -35,7 +36,7 @@ xcodebuild build-for-testing \
3536 CODE_SIGNING_ALLOWED=NO
3637```
3738
38- ```
39+ ``` bash
3940xcodebuild test-without-building \
4041 -xctestrun wda_build/Build/Products/WebDriverAgentRunner_iphonesimulator16.2-arm64.xctestrun \
4142 -destination " platform=iOS Simulator,name=iPhone 14 Pro"
@@ -55,7 +56,47 @@ xcodebuild test-without-building \
5556 provided `.xctestrun` file. Once this is done, `http://localhost:8100` will be able to receive
5657 commands for the target device.
5758
58- ## Capabilities for Prebuilt WDA with `appium:useXctestrunFile`, `appium:usePrebuiltWDA` or `appium:prebuildWDA`
59+ ## Preparation performance improvement ideas
60+
61+ ### Download Prebuilt WDA and run them with `appium:prebuiltWDAPath` and `appium:usePreinstalledWDA`
62+
63+ This approach allows the XCUITest driver to start WDA without running `xcodebuild` by using prebuilt WDA packages.
64+ We recommend this method if you don't need to modify the WDA source code.
65+
66+ [The Appium WebDriverAgent GitHub page](https://github.com/appium/WebDriverAgent/releases) provides
67+ downloads for WebDriverAgent packages for real devices and simulators.
68+ WebDriverAgent packages for real devices do not have embedded XCTest frameworks so that
69+ they can run on iOS 17+ devices. Please read [Run Preinstalled WebDriverAgentRunner](./run-preinstalled-wda.md)
70+ for more details about running on real devices. Understanding app signing is also important when working with real devices.
71+ Simulators need everything, so WDA package sizes for simulators are greater than for real devices.
72+ The [Release](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml) and
73+ [Building WebDriverAgent](https://github.com/appium/WebDriverAgent/actions/workflows/wda-package.yml)
74+ workflows may help with validating the build script.
75+
76+ [Run Preinstalled WebDriverAgentRunner](./run-preinstalled-wda.md) provides `appium:prebuiltWDAPath`
77+ and `appium:usePreinstalledWDA` capabilities.
78+ These capabilities allow the XCUITest driver to install prebuilt WDA specified with
79+ `appium:prebuiltWDAPath` and start it **without** running `xcodebuild`.
80+
81+ The `download-wda-sim` command helps to download the proper version of WDA for your XCUITest driver version
82+ for simulator use.
83+
84+ ```bash
85+ appium driver run xcuitest download-wda-sim --outdir=/path/to/target/directory
86+ ```
87+
88+ Then, starting a new session with capabilities below:
89+
90+ ``` json
91+ {
92+ "appium:usePreinstalledWDA" : true ,
93+ "appium:prebuiltWDAPath" : " /path/to/target/directory/WebDriverAgentRunner-Runner.app"
94+ }
95+ ```
96+
97+ The new session starts without an ` xcodebuild ` run.
98+
99+ ### Capabilities for Prebuilt WDA with ` appium:useXctestrunFile ` , ` appium:usePrebuiltWDA ` or ` appium:prebuildWDA `
59100
60101The XCUITest driver provides two capabilities that allow skipping the ` build-for-testing ` command,
61102and executing only the ` test-without-building ` command: __ ` appium:useXctestrunFile ` __ and
@@ -68,16 +109,15 @@ __`appium:bootstrapPath`__ (see [Capabilities](../reference/capabilities.md#webd
68109
69110This method can be used on both real devices and simulators, but real devices requires proper
70111signing as described in [ Run Preinstalled WebDriverAgentRunner] ( ./run-preinstalled-wda.md ) .
71- We recommend using this method for real devices.
72112
73113The capabilities can be used as follows:
74114
75115``` json
76116{
77117 "platformName" : " ios"
78118 "appium:automationName" : " xcuitest"
79- "appium:platformVersion": "15.5 ",
80- "appium:deviceName": "iPhone 12 ",
119+ "appium:platformVersion" : " 18.4 "
120+ "appium:deviceName" : " iPhone 16 "
81121 "appium:useXctestrunFile" : true ,
82122 "appium:bootstrapPath" : " /path/to/wda_build/Build/Products"
83123}
@@ -93,24 +133,3 @@ __`appium:prebuildWDA`__ lets the XCUITest driver build the WDA before running i
93133will be handled with ` appium:usePrebuiltWDA ` .
94134It might have additional building steps than with ` appium:derivedDataPath ` and ` appium:usePrebuiltWDA `
95135combination, but it could help ` appium:usePrebuiltWDA ` to not manage the WDA project.
96-
97- ## Capabilities for Prebuilt WDA with ` appium:prebuiltWDAPath ` and ` appium:usePreinstalledWDA `
98-
99- [ Run Preinstalled WebDriverAgentRunner] ( ./run-preinstalled-wda.md ) provides ` appium:prebuiltWDAPath `
100- and ` appium:usePreinstalledWDA ` capabilities.
101- It also achieves the same thing, but the ` appium:prebuiltWDAPath ` does not use ` xcodebuild ` .
102- The method will help to avoid ` xcodebuild ` related slowness.
103-
104- ## Download Prebuilt WDA
105-
106- [ The Appium WebDriverAgent GitHub page] ( https://github.com/appium/WebDriverAgent/releases ) provides
107- downloads for WebDriverAgent packages for real devices and simulators.
108- WebDriverAgent packages for real devices do not have embedded XCTest frameworks so that
109- they can run on iOS 17+ devices.
110- Simulators need everything, so package sizes for simulators are greater than for real devices.
111-
112- The [ Release] ( https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml ) and
113- [ Building WebDriverAgent] ( https://github.com/appium/WebDriverAgent/actions/workflows/wda-package.yml )
114- workflows may help with validating the build script.
115-
116- ` appium driver run xcuitest download-wda-sim ` command helps to download the prebuilt WDA.
0 commit comments