Skip to main content
This guide covers connecting and configuring iOS devices for testing with Qaptly using WebDriverAgent (WDA).

​
Prerequisites

​
On Your Mac

  • macOS 10.15 (Catalina) or later
  • Xcode installed (latest version recommended)
  • Apple ID (free tier works, but has limitations)
  • USB cable for device connection

​
On Your iOS Device

  • iOS 14.0 or higher
  • USB cable connected
  • Device unlocked and trusted

​
Initial Device Connection

​
Step 1: Connect Device

  1. Connect your iOS device via USB cable
  2. Unlock the device

​
Step 2: Trust Computer

When prompted on the device:
  1. Tap Trust on the “Trust This Computer?” dialog
  2. Enter your device passcode if prompted

​
Step 3: Verify in Xcode

  1. Open Xcode
  2. Go to Window > Devices and Simulators
  3. Your device should appear in the list
  4. Ensure status shows as connected

​
WebDriverAgent Setup

WebDriverAgent (WDA) is required for iOS automation. Qaptly includes a setup wizard to guide you through the process.

​
Opening the WDA Setup Wizard

  1. Open Pilot Control
  2. Find your iOS device in the list
  3. Click Setup WDA
  4. The WDA Setup Wizard opens

​
WDA Setup Flow

The wizard guides you through 4 steps:

​
Step 1: Download WDA Project

  1. Click Download WDA
  2. The WebDriverAgent project is downloaded to:
  3. Or select an existing WDA project location

​
Step 2: Configure Signing in Xcode

  1. Click Open in Xcode to open the WDA project
  2. In Xcode, select the WebDriverAgentRunner target
  3. Go to Signing & Capabilities
  4. Select your Team (your Apple ID)
  5. Fix any signing errors:
    • Change Bundle Identifier if needed (e.g., add .yourname)
    • Let Xcode manage signing automatically

​
Step 3: Launch WDA in Xcode

  1. Select your iOS device as the target
  2. Press ⌘+U (Product > Test) to build and run WDA
  3. Wait for WDA to install and start on device
  4. You may need to trust the developer profile on device:
    • Go to Settings > General > Device Management
    • Trust your developer profile

​
Step 4: Verify Status

  1. Return to Qaptly
  2. Click Verify Status
  3. Status should show “WDA Running”
  4. The setup is complete

​
Using WDA

​
Starting WDA

If WDA is not running:
  1. Open the WDA project in Xcode
  2. Select your device
  3. Press ⌘+U to start WDA

​
Stopping WDA

  1. In Xcode, press the Stop button
  2. Or press ⌘+.

​
WDA Port

WDA runs on port 8100 by default. Qaptly automatically detects and connects to WDA.

​
Signing Considerations

​
Free Apple ID

With a free Apple ID:
  • Apps expire after 7 days
  • You need to re-install WDA weekly
  • Limited to 3 app IDs per week
With a paid Apple Developer account ($99/year):
  • Apps last 1 year
  • No weekly reinstallation needed
  • More app ID slots

​
Enterprise Account

Enterprise certificates provide:
  • Longer validity
  • Simpler distribution
  • No device limit for development

​
Screen Streaming

​
Starting Stream

  1. Ensure WDA is running
  2. In Pilot Control, select your iOS device
  3. Click Start Stream
  4. The device screen appears in the streaming panel

​
Streaming Quality

iOS streaming may have slight delay compared to Android. This is normal due to the WDA architecture.

​
Multiple iOS Devices

​
Connecting Multiple Devices

  1. Connect each device via USB
  2. Trust each device
  3. Configure WDA for each device

​
Device Selection

Select the target device in:
  • Xcode’s scheme selector
  • Pilot Control’s device list

​
Troubleshooting

​
”Device Not Trusted”

  1. Disconnect and reconnect the device
  2. Tap Trust when prompted
  3. Enter passcode if required

​
WDA Build Fails

  1. Check code signing settings
  2. Ensure device is connected
  3. Clean build folder: Product > Clean Build Folder
  4. Try again

​
”Unable to Launch WDA”

  1. Check device is unlocked
  2. Verify developer profile is trusted on device
  3. Restart the device
  4. Try building WDA again

​
WDA Crashes on Start

  1. Uninstall WDA from device
  2. Clean build folder in Xcode
  3. Rebuild and reinstall

​
Device Not Appearing in Pilot Control

  1. Verify device is trusted
  2. Check Xcode recognizes device
  3. Ensure USB connection is stable
  4. Refresh device list in Pilot Control

​
”Profile Not Trusted”

On the iOS device:
  1. Go to Settings > General > VPN & Device Management
  2. Find your developer profile
  3. Tap Trust
  4. Confirm the trust action

​
Best Practices

  1. Keep device unlocked: Auto-lock can interrupt WDA
  2. Disable passcode temporarily: For long test sessions
  3. Use good USB cables: Poor cables cause connection issues
  4. Keep Xcode updated: Latest Xcode has best device support
  5. Document bundle ID changes: Track any signing modifications

​
Re-Setup After Expiration

If using a free Apple ID (7-day expiration):
  1. Delete WDA from device
  2. In Xcode, clean build folder
  3. Rebuild WDA with ⌘+U
  4. Trust the new profile on device
Related: