Add: ios-tagent docs

Introduction/README_zh.md

@@ -0,0 +1,105 @@
+iOS-Tagent 介绍
+=======================
+iOS-Tagent 是基于 facebook 的 [WebDriverAgent](https://github.com/facebook/WebDriverAgent) 项目上进行开发的 , 目的是为了对 [Airtest Project](http://airtest.netease.com/) 提供iOS平台的测试支持，我们在原项目的基础上进行了定制化的优化和功能调整。
+
+这个项目在如下版本上进行了开发和测试：
+
+| iOS       	| Xcode 	|
+|-----------	|-------	|
+| 10.x-12.x 	| 10.x  	|
+| ≥ 9.3       	| ≥ 9.3   	|
+
+其他版本的Xcode和iOS未经完整测试，可能会出现非预期的错误情况。
+
+
+# Airtest部署iOS平台测试
+在IOS平台进行Airtest测试，需要进行如下部署。
+
+## 1. iOS-Tagent
+在手机上创建一个WebDriver服务器，可用于远程控制iOS设备，定位UI元素
+
+
+* 1.1 下载 iOS-Tagent 到本地电脑
+
+    >git clone [email protected]:AirtestProject/iOS-Tagent.git
+
+* 1.2 使用Xcode打开 iOS-Tagent, 用数据线连接iPhone至Mac
+
+    >选择项目，在菜单栏 `product` -> `Scheme` -> `WebDriverAgentRunner` 
+
+    >选择设备，在菜单栏 `product` -> `Destination` -> 选择你的真机 
+
+    ![chooseScheme](/Introduction/chooseScheme.png "chooseScheme")
+
+* 1.3 启动Test，在菜单栏 `product` -> `Test`。当你看到这样的日志的时候，代表 iOS-Tagent 已经启动成功了
+```
+    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
+```
+
+    可以从以下了解更多的关于如何成功启动这个项目的方法 [here](https://github.com/facebook/WebDriverAgent/wiki/Starting-WebDriverAgent).和 [here](https://github.com/appium/appium/blob/master/docs/en/drivers/ios-xcuitest-real-devices.md)
+
+
+
+## 2. 设置代理
+[iproxy](https://github.com/libimobiledevice/libimobiledevice) 可以把iPhone端口映射到电脑端口，那么就可以通过访问电脑的端口访问到手机的端口了。
+
+一般情况下，需要通过设置usb代理的方式访问手机上的Agent，直接通过wifi对手机进行访问可能会出现问题，具体的原因可以参考 [Issues](https://github.com/facebook/WebDriverAgent/wiki/Common-Issues) 和 [detail](https://github.com/facebook/WebDriverAgent/issues/288)
+
+
+
+* 2.1 通过 Homebrew 安装iproxy
+
+    `$ brew install libimobiledevice`
+
+* 2.2 运行iproxy
+
+    `$ iproxy 8100 8100`
+
+
+启动成功后，可以试着在浏览器访问 http://127.0.0.1:8100/status ，如果访问成功并且可以看到一些json格式的手机信息，即表示启动成功。此时，访问 http://127.0.0.1:8100/inspector 可以看到iPhone屏幕投影在浏览器上
+
+
+有一点需要 **注意** 的，iproxy只能监听localhost，所以如果你想使用 Windows 连接iPhone，可以改用 [wdaproxy](https://github.com/openatx/wdaproxy)。具体步骤为：
+
+* 使用usb数据线连接iPhone至Mac
+* 在Mac上运行 wdaproxy，wdaproxy可以把iPhone端口映射到Mac端口，具体安装运行步骤可参考 https://github.com/openatx/wdaproxy 
+* 在Windows上的AirtestIDE iOS地址输入框，输入Mac的ip地址和端口，点击"connect"按钮
+
+
+## 3. AirtestIDE
+
+通过ip方式连接iPhone，实时刷新界面，可进行UI测试
+
+完成上面两个步骤后，就可以在AirtestIDE的iOS地址栏填入地址 http://127.0.0.1:8100 ，点击 “connect” 连接设备，开始编写你的Airtest测试脚本了
+
+
+<img src="./connectDevice.jpg" alt="connectDevice" title="connectDevice" width="50%" height="50%">
+
+
+![ios-airtestIDE](/Introduction/ios-airtestIDE.gif "ios-airtestIDE")
+
+
+
+# Q & A
+我们猜测你在部署过程中会遇到很多问题，所以整理了一份 [Q&A](./Introduction/question_zh.md)，你可以先看看，如果对于这个项目有问题和反馈建议，也欢迎到 [Issues](https://github.com/AirtestProject/iOS-Tagent/issues)里进行提出.
+1. [Xcode版本问题](./Introduction/question_zh.md#xcode版本)
+1. [申请开发者证书](./Introduction/question_zh.md#开发者证书)
+1. [登陆开发者账号](./Introduction/question_zh.md#登陆开发者账号)
+1. [设置开发者证书](./Introduction/question_zh.md#设置开发者证书)
+1. [Xcode failed to create provisioning profile](./Introduction/question_zh.md#buddle-identifier)
+1. [第一次安装，信任设备](./Introduction/question_zh.md#信任设备)
+
+
+# License
+iOS-Tagent 基于[WebDriverAgent](https://github.com/facebook/WebDriverAgent) 进行了定制化的开发和优化:
+
+
+[`WebDriverAgent` is BSD-licensed](LICENSE). We also provide an additional [patent grant](PATENTS).
+
+
+Have fun with Airtest!

Introduction/question.md

@@ -0,0 +1,49 @@
+# Q & A
+
+## Xcode version
+
+Different versions of Xcode need to be installed under specific Mac OS versions and can develop specific iOS versions. For more details, refer to [Wikipedia](https://en.wikipedia.org/wiki/Xcode).
+
+![versions](/Introduction/versions.png "versions")
+
+High version Xcode can't be installed on macOS with a lower version. 
+If you try to install Xcode by downloading Xcode.zip, you could then see errors like `cpio read error:Undefined error:0` when decompressing.
+
+![version_not_match](/Introduction/version_not_match2.png "version_not_match")
+
+
+
+## iOS Developer Account
+Apple Developer Certificate is required to deploy iOS-Tagent. Fortunately, Apple now allows us to register with Apple ID without payment.
+
+
+## Login to Xcode
+Select `Xcode` -> `Preferences` -> `Accounts` -> `Manage Certificates` -> below the left column `+` -> `iOS Development` to login Xcode.
+
+<img src="login.png" alt="login" tittle="login" width="50%"  height="50%">
+
+
+## Manage developer certificate
+After login, you need set up the developer certificate. `WebDriverAgent` -> `WebDriverAgent-Runner` -> `General` -> `Signing` select your certificate
+
+<img src="signing.png" alt="signing" tittle="signing" width="70%"  height="70%">
+
+
+## bundle identifier
+If you are using a free developer certificate, you may see the error `Xcode failed to create provisioning profile` 
+
+<img src="FailID.png" alt="FailID" tittle="FailID" width="50%"  height="50%">
+
+This error can be fixed by changing the Bundle Identifier `Build Settings` -> `Product Bundle Identifier`. This should be a unique identifier, you can set up your own.Here's an example 'com.xxx.webDriverAgent-test123'. 
+
+![bundleId](/Introduction/bundleId.png "set up bundleId")
+
+
+## Trusting certificates
+The first time you install iOS-Tangent to your iPhone, you will get a pop up as shown below.  Select Settings
+The first time you installed iOS-Tagent to your iPhone, you will get a pop up as shown below. Select `Settings ` -> `General ` -> `Device Management`  ->  to trust the developer certificate on your iPhone. Then retry "test" in Xcode, it should work. See [Apple documentation](https://support.apple.com/en-us/HT204460)
+
+
+![untrusted](/Introduction/untrusted.jpg "untrusted")
+
+![trust_dev](/Introduction/trust_dev2.png "trust_dev")

Introduction/question_zh.md

@@ -0,0 +1,45 @@
+# Q & A
+
+## Xcode版本
+不同版本的Xcode需要在指定版本的mac os系统下安装，能开发指定版本的iOS，具体可参考[维基百科](https://en.wikipedia.org/wiki/Xcode)
+
+![versions](/Introduction/versions.png "versions")
+
+高版本 Xcode 不能在低版本 macOS 下安装，强行下载 xip 安装包进行安装，在解压的时候也会出现如下问题。如出现如`cpio read error:Undefined error:0` 、  `应用程序Xcode的这个版本不能与此版本的OS X配合使用`等问题，最好还是更新 os 系统或者更换低版本Xcode
+
+![version_not_match](/Introduction/version_not_match.png "version_not_match")
+
+
+
+## 开发者证书
+部署iOS测试平台需要苹果开发者证书，现在使用个人Apple ID登陆即可，不需要另外注册付费开发者账号
+
+
+## 登陆开发者账号
+开发者账号登陆过程为 `Xcode` -> `Preferences` -> `Accounts` -> `Manage Certificates` -> 左栏下方 `+` -> `iOS Development`，如有遇到其他问题，可自行百度
+
+<img src="login.png" alt="login" tittle="login" width="50%"  height="50%">
+
+
+## 设置开发者证书
+登陆后，需在项目设置开发者证书，具体步骤为`WebDriverAgent` -> `WebDriverAgent-Runner` -> `General` -> `Signing` 选择自己的开发者证书
+
+<img src="signing.png" alt="signing" tittle="signing" width="70%"  height="70%">
+
+
+## buddle identifier
+使用了免费开发者证书的用户，可能会遇到问题 `Xcode failed to create provisioning profile` 
+
+<img src="FailID.png" alt="FailID" tittle="FailID" width="50%"  height="50%">
+
+可以通过修改 `Build Settings` -> `Product Bundle Identifier`解决。Xcode会联网检查Product Bundle Identifier，此字段要求唯一标志，多试几个，总有可以的。如 ('com.xxx.webDriverAgent-test123')
+
+![bundleId](/Introduction/bundleId.png "set up bundleId")
+
+
+## 信任设备
+第一次安装 iOS-Tagent 的时候，你会遇到下面的错误提示框。这时候需要信任应用程序才可以进行启动，在手机上 `设置` -> `通用` -> `设备管理` 从而对应用程序进行信任，才可以进行运行 (可以查看 [Apple documentation](https://support.apple.com/en-us/HT204460))。之后 Xcode 重新启动`test`即可，会黑屏一下接着正常执行。
+
+![untrusted](/Introduction/untrusted.jpg "untrusted")
+
+![trust_dev](/Introduction/trust_dev.png "trust_dev")

README.md

@@ -1,56 +1,140 @@
-# WebDriverAgent
+iOS-Tagent Introduction
+=======================
 
-[![NPM version](http://img.shields.io/npm/v/appium-webdriveragent.svg)](https://npmjs.org/package/appium-webdriveragent)
-[![Downloads](http://img.shields.io/npm/dm/appium-webdriveragent.svg)](https://npmjs.org/package/appium-webdriveragent)
+iOS-Tagent is a project based on facebook [WebDriverAgent](https://github.com/facebook/WebDriverAgent) and intend to fit [Airtest Project](http://airtest.netease.com/).
 
-[![Release](https://github.com/appium/WebDriverAgent/actions/workflows/publish.js.yml/badge.svg)](https://github.com/appium/WebDriverAgent/actions/workflows/publish.js.yml)
 
-[![GitHub license](https://img.shields.io/badge/license-BSD-lightgrey.svg)](LICENSE)
+We make some customized optimization and adjustments to it and it works well in:
 
-WebDriverAgent is a [WebDriver server](https://w3c.github.io/webdriver/webdriver-spec.html) implementation for iOS that can be used to remote control iOS devices. It allows you to launch & kill applications, tap & scroll views or confirm view presence on a screen. This makes it a perfect tool for application end-to-end testing or general purpose device automation. It works by linking `XCTest.framework` and calling Apple's API to execute commands directly on a device. WebDriverAgent is developed for end-to-end testing and is successfully adopted by [Appium](http://appium.io) via [XCUITest driver](https://github.com/appium/appium-xcuitest-driver).
+| iOS       	| Xcode 	|
+|-----------	|-------	|
+| 10.x-12.x 	| 10.x  	|
+| ≥ 9.3       	| ≥ 9.3   	|
 
-## Features
- * Both iOS and tvOS platforms are supported with devices & simulators
- * Implements most of [WebDriver Spec](https://w3c.github.io/webdriver/webdriver-spec.html)
- * Implements part of [Mobile JSON Wire Protocol Spec](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md)
- * USB support for devices is implemented via [appium-ios-device](https://github.com/appium/appium-ios-device) library and has zero dependencies on third-party tools.
- * Easy development cycle as it can be launched & debugged directly via Xcode
- * Use [Mac2Driver](https://github.com/appium/appium-mac2-driver) to automate macOS apps
+Other versions of Xcode and iOS are not fully tested and may cause unexpected errors.
 
-## Getting Started On This Repository
 
-You need to have Node.js installed for this project.
+If you need README in Chinese, click here([如需中文文档，请点击这里](./Introduction/README_zh.md))
 
-After it is finished you can simply open `WebDriverAgent.xcodeproj` and start `WebDriverAgentRunner` test
-and start sending [requests](https://github.com/facebook/WebDriverAgent/wiki/Queries).
 
-More about how to start WebDriverAgent [here](https://github.com/facebook/WebDriverAgent/wiki/Starting-WebDriverAgent).
+# Getting Started
 
-## Known Issues
-If you are having some issues please checkout [wiki](https://github.com/facebook/WebDriverAgent/wiki/Common-Issues) first.
+To perform Airtest in iOS, the following steps are required
 
-## For Contributors
-If you want to help us out, you are more than welcome to. However please make sure you have followed the guidelines in [CONTRIBUTING](CONTRIBUTING.md).
+## 1. iOS-Tagent
+Create a WebDriver server on your iPhone which makes it possible to remote control iOS devices and locate UI elements.
 
-## Creating Bundles
+* 1.1 Clone or Download iOS-Tagent
 
-`npm run bundle`
+    > git clone [email protected]:AirtestProject/iOS-Tagent.git
 
-Then, you find `WebDriverAgentRunner-Runner-sim-<version>.zip`  for iOS and `WebDriverAgentRunner-Runner-tv_sim-<version>.zip` for tvOS files in the current directory.
+* 1.2 Open iOS-Tagent with Xcode and connect your iPhone to Mac with a data cable
 
-## License
+    > Select `product` -> `Scheme` -> `WebDriverAgentRunner` in the top menu of Xcode
 
-[`WebDriverAgent` is BSD-licensed](LICENSE). We also provide an additional [patent grant](PATENTS).
+    > Then select `product` -> `Destination` -> your iPhone
 
-## Third Party Sources
+    ![chooseScheme](/Introduction/chooseScheme.png "chooseScheme")
 
-WebDriverAgent depends on the following third-party frameworks:
-- [CocoaHTTPServer](https://github.com/robbiehanson/CocoaHTTPServer)
-- [RoutingHTTPServer](https://github.com/mattstevens/RoutingHTTPServer)
+* 1.3 Start tests by click `product` -> `Test`. When something like this shows in the log, it means that iOS-Tagent have started successfully.
 
-These projects haven't been maintained in a while. That's why the source code of these
-projects has been integrated directly in the WebDriverAgent source tree.
+```
+    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
+```
 
-You can find the source files and their licenses in the `WebDriverAgentLib/Vendor` directory.
+More about how to start WebDriverAgent [here](https://github.com/facebook/WebDriverAgent/wiki/Starting-WebDriverAgent) and [here](https://github.com/appium/appium/blob/master/docs/en/drivers/ios-xcuitest-real-devices.md)
 
-Have fun!
+## 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](https://github.com/facebook/WebDriverAgent/wiki/Common-Issues) and [detail](https://github.com/facebook/WebDriverAgent/issues/288)
+
+The original source code of iproxy is shown in https://github.com/libimobiledevice/libimobiledevice
+
+* 2.1 Install iproxy with Homebrew
+
+    `$ brew install libimobiledevice`
+
+* 2.2 Run iproxy
+
+    `$ iproxy 8100 8100`
+
+Then try to access http://127.0.0.1:8100/status 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 http://127.0.0.1:8100/inspector .
+
+**Note** that iproxy can only listen to localhost. If you want to connect iPhone on AirtestIDE on a windows OS, you can try [wdaproxy](https://github.com/openatx/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 https://github.com/openatx/wdaproxy .
+* 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 "http://127.0.0.1:8100" in the iOS address input box of AirtestIDE. Click button "connect" to connect your iPhone and start your Airtest test.
+
+<img src="./Introduction/connectDevice.jpg" alt="connectDevice" title="connectDevice" width="50%" height="50%">
+
+![image](./Introduction/ios-inspector.gif)
+
+Note that you can also view the device Hierarchy
+
+This feature work with [Poco](https://github.com/AirtestProject/Poco) and AirtestIDE.
+
+# Q & A
+
+We have collected a series of common issues on our [Q&A](./Introduction/question.md). 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](https://github.com/AirtestProject/iOS-Tagent/issues).
+
+
+1. [Xcode version](./Introduction/question.md#xcode-version)
+1. [iOS Developer Account](./Introduction/question.md#ios-developer-account)
+1. [Login to Xcode](./Introduction/question.md#login-to-xcode)
+1. [Manage developer certificate](./Introduction/question.md#manage-developer-certificate)
+1. [Xcode failed to create provisioning profile](./Introduction/question.md#bundle-identifier)
+1. [Trust certificate](./Introduction/question.md#trusting-certificates)
+
+
+
+# API status
+
+This project intend to work with
+[AirtestIDE](http://airtest.netease.com/) and [AirtestFramework](https://github.com/AirtestProject/Airtest)
+
+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
+
+except:
+
+> -   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
+
+
+# License
+
+This project is based on [WebDriverAgent](https://github.com/facebook/WebDriverAgent) :
+
+[**WebDriverAgent** is BSD-licensed](./LICENSE) . We also provide an additional [patent grant](./PATENTS).
+
+Have fun with Airtest!