If every iOS Appium session in your CI job spends a long time before the first command runs, the time usually goes into WebDriverAgent (WDA). The XCUITest driver does not talk to the device directly. It starts WDA, an HTTP server that runs on the device as an XCTest runner, and proxies your commands to it. By default it starts WDA through xcodebuild, which builds the project and then launches it on the device.
Short answer: do not let each session build WDA. Let sessions reuse a WDA that is already running, build WDA once per job and launch it from the build products, use a preinstalled WDA on iOS 17 and later, or start WDA yourself and attach to it. Before you change anything, read the startup from the Appium server log, so you know which step is slow.
What happens at session start
With default capabilities on a simulator or a real device, the driver:
- Checks whether a WDA from an earlier session is still running on the same port, and reuses it if it can (more on this below).
- If not, runs one command:
xcodebuild build-for-testing test-without-building. The first part builds theWebDriverAgentRunnertest bundle, the second installs and runs it on the device. - Polls WDA's
/statusendpoint until it answers. The limit isappium:wdaLaunchTimeout, 60000 ms by default.
Two more things can add time:
- After a driver upgrade that brings a newer WDA, the first session cleans the WDA project before building it. The log says
Cleaning up the WebDriverAgent project after the module upgrade has happened. That build starts from scratch. - When startup fails, the driver can try again.
appium:wdaStartupRetriesis the number of tries to build and launch WDA: 2 on simulators and 1 on real devices by default, withappium:wdaStartupRetryInterval(10000 ms by default) between them. A session that starts on its second try has already paid for one failed build and launch.
Step 1: find the slow step in the log
Start the Appium server with timestamps, so you can measure the gap between lines:
appium --log-timestamp
Then look for these lines during session creation. They come from the driver and WDA source:
Will reuse previously cached WDA instance at 'http://...:8100'— the session reused a running WDA. No build happened.WDA is currently not running. There is nothing to cache— no WDA was running, so this session will start one.Will not reuse running WDA since ...— a WDA was running, but the driver refused it. The rest of the line says why: a different bundle id, or a WDA version that does not match the one bundled with your driver.Beginning test with command 'xcodebuild ...'— thexcodebuildrun starts here. The arguments show whether it builds (build-for-testing) or only launches (test-without-building).WebDriverAgent successfully started after <n>ms— WDA answered/status. The number is the time sincexcodebuildstarted.
If you need to see what xcodebuild itself is doing during that time, set appium:showXcodeLog: true for one run. Expect a lot of output.
If the slow part is not between these lines, WDA is not your problem. Booting a simulator, installing the app or resetting it all happen in the same session start. The driver's WDA slowness guide covers the slow steps that happen after WDA is up.
Fix 1: let sessions reuse the running WDA
This one costs nothing. appium:useNewWDA defaults to false. With that value the driver "will try to detect currently running WDA listener executed by previous testing session(s) and reuse it if possible". The docs call this "highly recommended for real device testing and to speed up suites of multiple tests in general". At the end of a session started through xcodebuild, the driver leaves WDA running for the next one.
Reuse breaks in a few common ways:
appium:useNewWDA: trueis set. It uninstalls WDA and builds it again for every session. Remove it unless you really need different WDA startup options per session.- The bundle id changes between sessions. If the running WDA has a different bundle id from the one this session expects (
appium:updatedWDABundleId), the driver will not reuse it. - The driver was upgraded. A running WDA from an older driver version is not reused.
- Nothing is left running. Reuse needs the earlier WDA to still be listening on the same port (
appium:wdaLocalPort, 8100 by default). If each test tears the environment down, the next session finds nothing to reuse.
With reuse working, only the first session of a job pays for the build. Each later session on the same device logs Will reuse previously cached WDA instance.
Fix 2: build once per job, then launch from the build products
Even the first session does not need to build. You can split the build out of the session. Run build-for-testing yourself as a CI step, then let sessions run only test-without-building. The docs' simulator example, run from the WDA project folder (appium driver run xcuitest open-wda opens that project in Xcode, and its path is in the command's log output):
xcodebuild build-for-testing \
-project WebDriverAgent.xcodeproj \
-derivedDataPath wda_build \
-scheme WebDriverAgentRunner \
-destination "platform=iOS Simulator,name=iPhone 14 Pro" \
CODE_SIGNING_ALLOWED=NO
This writes WebDriverAgentRunner-Runner.app and an .xctestrun file under wda_build/Build/Products. Point the session at that folder:
{
"appium:useXctestrunFile": true,
"appium:bootstrapPath": "/path/to/wda_build/Build/Products"
}
The driver then runs only test-without-building. It does not check build dependencies and does not try to build the project.
Things to know:
- Real devices need a signed build. Use a real-device destination, drop
CODE_SIGNING_ALLOWED=NO, and sign with your team and bundle id. On CI the keychain must be unlocked for that build step. Our code 65 article covers both. - Build for the lowest OS version you test on. The capability reference warns that a WDA built for a newer iOS version can fail to load on an older one, while the other direction works.
- Two alternatives exist.
appium:usePrebuiltWDAwithappium:derivedDataPathdoes the same thing, but the docs warn it "may fail ifxcodebuildcannot find or handle the.xctestrunfile properly".appium:prebuildWDAlets the driver build first and then launch asusePrebuiltWDAwould. That moves the build, but the session still pays for it.
Fix 3: on iOS 17 and later, use a preinstalled WDA
From iOS/tvOS 17 (watchOS 10), the driver can launch a WDA that is already installed on the device, with no xcodebuild run at all:
{
"appium:usePreinstalledWDA": true,
"appium:updatedWDABundleId": "com.yourcompany.WebDriverAgentRunner"
}
The driver looks for <updatedWDABundleId>.xctrunner on the device (the default is com.facebook.WebDriverAgentRunner.xctrunner) and launches it. To install WDA once, run Product → Test on the WebDriverAgentRunner scheme in Xcode, or use a third-party installer.
You can also let the driver install a package for you with appium:prebuiltWDAPath. The driver can download prebuilt packages that match its WDA version:
appium driver run xcuitest download-wda -- --outdir=/path/to/wda --kind=sim --platform=ios
Note that with appium:prebuiltWDAPath the driver installs the package again in every session, because test bundles cannot be versioned. That is still faster to set up than a build, but it is not free. Packages for real devices must be signed.
Things to know:
- It is iOS 17+ only. For older versions, the docs point you to the default
xcodebuildflow or toappium:webDriverAgentUrl. - On a real device, WDA starts over a RemoteXPC tunnel. On iOS/tvOS 17–26 the driver falls back to
xcrun devicectlif RemoteXPC is not available. On iOS/tvOS 27 and later that fallback is disabled, so the tunnel must work. - The device needs its developer disk image mounted. Opening Xcode with the device connected mounts it.
appium:wdaStartupRetriesdoes not apply. It only covers thexcodebuildflow.
Fix 4: start WDA yourself and attach to it
If your CI already manages devices, you can run WDA outside Appium and give each session its URL:
{
"appium:udid": "<device udid>",
"appium:webDriverAgentUrl": "http://localhost:8100"
}
Appium then "will connect to an existing WebDriverAgent instance at this URL instead of starting a new one". It also skips its cleanup of leftover WDA processes and, for real devices, its check of which devices are available. You own WDA's lifecycle: keeping it running, restarting it after a crash, and the port forward to the device. If the device's WDA port differs from the local one, set appium:wdaRemotePort too.
Parallel runs: give each device its own derived data
When several sessions start WDA on one Mac at the same time, give each device a unique value for these capabilities:
appium:udid— the device or simulator.appium:wdaLocalPort— the default is8100.appium:derivedDataPath— the docs say a unique path per driver instance helps "to avoid possible conflicts and to speed up the parallel execution".
The driver starts WDA under a lock. Sessions that share a derived data path wait for each other. Without a unique path, the log suggests it: Consider setting a unique 'derivedDataPath' capability value for each parallel driver instance to avoid conflicts and speed up the building process. The port matters for reuse too: when the driver reuses a running WDA, it logs Set the wdaLocalPort capability to a value different from <port> if this is an undesired behavior, where <port> is the port in use (8100 by default).
Raising timeouts does not make startup faster
appium:wdaLaunchTimeout (60000 ms) sets how long the driver waits for WDA to answer /status at startup. Raising it can turn a timeout into a slow success, but the build still runs every time. Raise it when your machine needs longer once WDA is otherwise healthy. Use Fixes 1–4 to stop paying for the build.
appium:wdaConnectionTimeout (240000 ms) is a different setting: it limits how long the driver waits for each response from a running WDA, not the startup.
Checklist
- Start Appium with
--log-timestampand find the gap: reuse lines,Beginning test with command 'xcodebuild ...',WebDriverAgent successfully started after <n>ms. - Remove
appium:useNewWDA: trueunless you need it. Keep the bundle id and port stable between sessions. - Build WDA once per job and launch it with
useXctestrunFileandbootstrapPath. - On iOS 17+, use
usePreinstalledWDA. AddprebuiltWDAPathonly if the driver should install the package. - If you manage WDA yourself, attach with
webDriverAgentUrl. - For parallel runs, give each device its own
udid,wdaLocalPortandderivedDataPath. - Treat higher timeouts and retries as a last resort, not as a speed fix.
Sources
Checked against the Appium XCUITest driver documentation and source (driver 12.22.2, appium-webdriveragent 16.17.6) on 2026-10-28:
- Capabilities reference (
useNewWDA,wdaLaunchTimeout,wdaConnectionTimeout,wdaStartupRetries,useXctestrunFile,usePrebuiltWDA,prebuildWDA,usePreinstalledWDA,prebuiltWDAPath,webDriverAgentUrl,derivedDataPath,showXcodeLog) - Run prebuilt WDA and run preinstalled WDA
- Attach to a running WDA
- Running tests in parallel
- WebDriverAgent slowness
- Driver scripts (
open-wda,download-wda) - Log lines and startup order: driver source
lib/commands/wda/and WDA package sourcepackages/webdriveragent/lib/