Skip to content
Go to file


Failed to load latest commit information.
Latest commit message
Commit time

iOS-Tagent Introduction

iOS-Tagent is a project based on facebook WebDriverAgent and intend to fit Airtest Project.

We make some customized optimization and adjustments to it and it works well in:

iOS Xcode
≥ 13 11.x
10.x-12.x 10.x
≥ 9.3 ≥ 9.3

Other versions of Xcode and iOS are not fully tested and may cause unexpected errors.

If you need README in Chinese, click here(如需中文文档,请点击这里)

Getting Started

To perform Airtest in iOS, the following steps are required

1. iOS-Tagent

Create a WebDriver server on your iPhone which makes it possible to remote control iOS devices and locate UI elements.

  • 1.1 Clone or Download iOS-Tagent

    git clone

  • 1.2 Open iOS-Tagent with Xcode and connect your iPhone to Mac with a data cable

    Select product -> Scheme -> WebDriverAgentRunner in the top menu of Xcode

    Then select product -> Destination -> your iPhone


  • 1.3 Start tests by click product -> Test. When something like this shows in the log, it means that iOS-Tagent have started successfully.

    Test Suite 'All tests' started at 2017-01-23 15:49:12.585
    Test Suite 'WebDriverAgentRunner.xctest' started at 2017-01-23 15:49:12.586
    Test Suite 'UITestingUITests' started at 2017-01-23 15:49:12.587
    Test Case '-[UITestingUITests testRunner]' started.
    t =     0.00s     Start Test at 2017-01-23 15:49:12.588
    t =     0.00s     Set Up

More about how to start WebDriverAgent here and here

2. Set up proxy

iproxy maps the iPhone port to the Mac port, so you can access the phone by accessing the Mac.

You need to set up the usb proxy to access the Agent on the actual phone, as there may be problems when accessing directly through wifi. For more information, check Issues and detail

The original source code of iproxy is shown in

  • 2.1 Install iproxy with Homebrew

    $ brew install libimobiledevice

  • 2.2 Run iproxy

    $ iproxy 8100 8100

Then try to access in your mac browser. If a json data about your iPhone is returned, it means iproxy started successfully. Moreover, you can see iPhone screen projected on the browser by visiting .

Note that iproxy can only listen to localhost. If you want to connect iPhone on AirtestIDE on a windows OS, you can try wdaproxy. The specific steps are as follows:

  • Connect iPhone to Mac with a usb cable.
  • Run wdaproxy in Mac. wdaproxy can map the iPhone port to the Mac port too. You can see the installation instruction in .
  • Fill ip address and port of the iPhone (retrieved in the previous step) in the input box of AirtestIDE on Windows and click button "connect".

3. AirtestIDE

Connect to the iPhone by ip address, refresh screen, run tests

After the above two steps, you can fill "" in the iOS address input box of AirtestIDE. Click button "connect" to connect your iPhone and start your Airtest test.



Note that you can also view the device Hierarchy

This feature work with Poco and AirtestIDE.

Q & A

We have collected a series of common issues on our Q&A. If you have any questions, please take a look at these first. If you can't find your issue here, or you have any suggestion, please feel free to post it in Issues.

  1. Xcode version
  2. iOS Developer Account
  3. Login to Xcode
  4. Manage developer certificate
  5. Xcode failed to create provisioning profile
  6. Trust certificate

API status

This project intend to work with AirtestIDE and AirtestFramework

Common API in Airtest is supported

  • start_app: OK
  • stop_app: OK
  • snapshot: OK
  • home: OK
  • touch: OK
  • swipe: OK
  • text: OK
  • wait: OK
  • exists: OK
  • find_all: OK
  • assert_exists: OK
  • assert_not_exists: OK


  • wake: Not supported now (may use 'home' instead)
  • keyevent: Only support 'home' event
  • clear_app: Not supported now
  • install: Not supported now
  • uninstall: Not supported now


This project is based on WebDriverAgent :

WebDriverAgent is BSD-licensed . We also provide an additional patent grant.

Have fun with Airtest!