[Katalon mobile IOS] Unable to launch WebDriverAgent

Academy Certification
2

To resolve the WebDriverAgent (WDA) launch failure in Katalon for iOS testing:

1. Fix WebDriverAgent Signing Issues

  • Problem: WDA requires valid code signing to run on simulators or real devices.
  • Solution:
    a. Open the WDA project in Xcode:
    • Navigate to Applications/Katalon Studio.app/Contents/Resources/appium/WebDriverAgent.
    • Open WebDriverAgent.xcodeproj in Xcode.
      b. Select your team in Xcode:
    • Go to Signing & Capabilities → Select your Apple Developer account for WebDriverAgentLib and WebDriverAgentRunner targets.
    • Ensure “Automatically manage signing” is enabled.
      c. Build and run WDA manually in Xcode to confirm it works (Debug on Simulator/Device).

2. Adjust Capabilities in Katalon

  • Add these capabilities to your mobile setup:
'appium:wdaLaunchTimeout': 120000, // Increase timeout to 120 seconds  
'appium:useNewWDA': true, // Force fresh WDA instance  
'appium:wdaStartupRetries': 4, // Add retries  
'appium:showXcodeLog': true, // Enable Xcode logs  
'appium:simpleIsVisibleCheck': true, // Simplify visibility checks
  • Remove conflicting flags: Disable noReset or fullReset temporarily for testing.

3. Use a Unique WDA Port

  • Problem: Port conflicts (e.g., 49411) can block WDA startup.
  • Workaround: Assign a unique unused port (e.g., 8200):
'appium:wdaLocalPort': 8200

4. Update Dependencies

  • Update Appium:
npm install -g appium@latest
  • Install Carthage: WDA requires Carthage dependencies.
brew install carthage  
cd /Applications/Katalon\ Studio.app/Contents/Resources/appium/WebDriverAgent  
carthage bootstrap --platform iOS

5. Verify Simulator/Device Setup

  • For Simulators:
    • Reset the simulator via Hardware → Erase All Content and Settings.
    • Ensure the correct iOS version (e.g., 16.2) is installed in Xcode → Preferences → Components.
  • For Real Devices:
    • Trust the device on your Mac: Enter the device passcode when prompted.
    • Ensure the device UDID is correct (check via xcrun instruments -s devices).

6. Check Environment Permissions

  • Grant Full Disk Access to Terminal, Xcode, and Katalon in System Settings → Security & Privacy.
  • For macOS Ventura+, allow “Allow Remote Automation” in Settings → Developer on the iOS device/simulator.

7. Troubleshoot via Appium Logs

  • Enable verbose logging in Katalon:
'appium:showIOSLog': true,  
'appium:logLevel': 'debug'
  • Look for errors like Failed to launch WDA or code signing blocked in Console.app logs.

8. Switch to WDA v4+ (Manual Installation)

If Katalon’s bundled WDA is outdated:

  1. Clone the latest WDA:
git clone https://github.com/appium/WebDriverAgent.git
  1. Follow Appium’s WDA setup guide to install and link it to Katalon.

Alternative Solutions

  • Use Appium Desktop to manually test WDA connectivity first.
  • Try a lower iOS version (e.g., 15.7) if issues persist with iOS 16+.

Final Checks:

  1. Retry the test after closing/reopening Xcode and Katalon.
  2. Ensure your Java environment variables are properly set.
  3. Reinstall Katalon Studio if the issue persists.

If the problem continues, share logs from Xcode and Katalon’s Console tab for specific error analysis