add chinese docs

ajitkatte · Nov 3, 2013 · 7983037 · 7983037
1 parent 1ddc5f4
commit 7983037
Show file tree

Hide file tree

Showing 8 changed files with 523 additions and 0 deletions.
diff --git a/docs/cn/README.md b/docs/cn/README.md
@@ -0,0 +1,125 @@
+# Appium
+
+> Appium是一个支持原生,混合和移动web apps的开源的跨平台测试框架工具
+
+[![NPM version](https://badge.fury.io/js/appium.png)](https://npmjs.org/package/appium)
+[![Build Status](https://api.travis-ci.org/appium/appium.png?branch=master)](https://travis-ci.org/appium/appium)
+
+## 支持平台
+
+* iOS
+* Android
+* FirefoxOS
+
+## 为什么选择appium ?
+
+1. 你不需要以任何方式重新编译或者修改你的app,就可以在所有的平台上使用标准的自动化APIs
+2. 你可以用你喜欢的开发工具使用任何 [WebDriver](https://code.google.com/p/selenium/wiki/JsonWireProtocol) 兼容的语言来编写测试用例.比如
+Java, [Objective-C](https://github.com/appium/selenium-objective-c),
+   JavaScript with Node.js (in both [callback](https://github.com/admc/wd) and [yield-based](https://github.com/jlipps/yiewd) flavours),
+   PHP, Python, [Ruby](https://github.com/appium/ruby_lib), C#, Clojure, 或者 Perl 
+   可以使用标准的Selenium WebDriver API和特定语言的客户端库.
+3. 你可以使用任何测试框架.
+
+依托  [WebDriver](https://code.google.com/p/selenium/wiki/JsonWireProtocol) 意味着你可以押宝在一个已经成为事实上标准的独立,自由和开放的协议.而不会被限制在任何的专利中
+
+
+如果在没有使用Appium的情况,你使用了Apple的UIAutomation库就只能通过Javascript,并且只能通过Instruments application插桩应用来运行你的测试.
+同样的,在Google的UiAutomator体系下,你只能用Java写你的测试案例.
+Appium最终开启了跨平台原生移动自动化的可能.
+
+## 依赖
+
+你的环境需要配置好运行测试相关的特定移动平台,下面列出相关的依赖平台
+如果你想通过`npm install`来运行appium, 为Appium研究和贡献力量.你需要[node.js and npm](http://nodejs.org) 0.8 或者更高版本 (`brew install node`).
+
+### IOS依赖
+
+* Mac OS X 10.7 or higher, 10.8.4 recommended
+* XCode &gt;= 4.6.3
+* Apple Developer Tools (iPhone simulator SDK, command line tools)
+* [Ensure you read our documentation on setting yourself up for iOS testing!](https://github.com/appium/appium/blob/master/docs/cn/running-on-osx.cn.md#ios)
+
+### android依赖
+
+* [Android SDK](http://developer.android.com) API &gt;= 17 (Additional features require 18)
+* Appium支持OS X上的Android, Linux和Windows上的beta支持.确保你通过如下的指示来配置你需要运行测试的不同系统的环境
+  * [linux](https://github.com/appium/appium/blob/master/docs/cn/running-on-linux.cn.md) 
+  * [osx](https://github.com/appium/appium/blob/master/docs/cn/running-on-osx.cn.md#android)
+  * [windows](https://github.com/appium/appium/blob/master/docs/cn/running-on-windows.cn.md)
+
+### FirefoxOS Requirements
+
+* [Firefox OS Simulator](https://developer.mozilla.org/en/docs/Tools/Firefox_OS_Simulator)
+
+## 快速开始
+启动Appium server,并运行用你喜欢的 [WebDriver](https://code.google.com/p/selenium/wiki/JsonWireProtocol) 兼容的语言编写的测试用例.
+你可以用node.js或者下面的应用程序来运行Appium
+
+### 使用Node.js
+
+    $ npm install -g appium
+    $ appium &
+
+### 使用app
+
+* [下载 Appium app](https://github.com/appium/appium/releases)
+* 运行它! 
+
+## 为Appium编写测试
+
+我们支持 [Selenium WebDriver JSON Wire Protocol](https://github.com/appium/appium/wiki/JSON-Wire-Protocol:-Supported-Methods) 的一个子集
+首先还需要指定特定移动平台相关的 [desired capabilities](https://github.com/appium/appium/blob/master/docs/cn/caps.cn.md) 来通过appium运行你的测试
+
+你可以通过 [WebDriver](https://code.google.com/p/selenium/wiki/JsonWireProtocol) 的元素定位策略的一个子集来定位元素
+更多信息请参考 [finding elements](https://github.com/appium/appium/blob/master/docs/cn/finding-elements.cn.md) 
+
+
+我们也对 JSON Wire Protocol for [automating mobile gestures](https://github.com/appium/appium/blob/master/docs/cn/gestures.cn.md) 做了一些扩展以支持像 tap, flick, 和 swipe 这样的动作(松开,按压,滑动等手机手势)
+
+你也可以在混合模式下自动化你的用HTML5构建的Web页面 [hybrid app
+guide](https://github.com/appium/appium/blob/master/docs/cn/hybrid.cn.md)
+这个代码地址包含了 [很多不同语言的测试例子](https://github.com/appium/appium/tree/master/sample-code/examples/node)!
+
+
+想了解全部的Appium的文档页面,请访问 [这个目录](https://github.com/appium/appium/blob/master/docs/).
+
+## 工作原理
+
+Appium通过多种原生自动化框架来提供基于Selenium的 [WebDriver JSON wire protocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol) api
+
+Appium驱动Apple的UIAutomation库提供IOS支持. UIAutomation基于[Dan Cuellar's](http://github.com/penguinho)
+
+Android支持上, 在新版本的Android使用了Uiautomator框架,老版本的android上使用了
+[Selendroid](http://github.com/DominikDary/selendroid) 
+
+FirefoxOS的支持依赖一个基于Gecko平台并且兼容WebDriver的自动化驱动[Marionette](https://developer.mozilla.org/en-US/docs/Marionette),不过暂不翻译了.因为暂时用不到
+
+
+## 如何贡献代码
+可以看下我们的文档  [contribution documentation](https://github.com/appium/appium/blob/master/CONTRIBUTING.md) 
+以了解如何从源代码中进行编译,测试和运行
+
+
+## 其他项目的授权和灵感来源
+
+[Credits](https://github.com/appium/appium/blob/master/docs/cn/credits.cn.md)
+
+## 邮件列表
+
+声明和公告经常放到讨论组 [Discussion Group](https://groups.google.com/d/forum/appium-discuss), 需要注册
+
+## 问题定位
+
+我们增加了一个 [问题定位指南](https://github.com/appium/appium/blob/master/docs/cn/troubleshooting.cn.md).
+如果你遇到一些问题,请看下这个问的那个.它包含了一些常见的错误说明,以及在无法解决的情况如何和社区联系
+
+
+## 使用Robots扩展
+可以使用appium的一些robots扩展.或者其他的robots.想了解更多可以看看 [Appium Robots](https://github.com/appium/robots)
+
+
+## 翻译工作
+文档翻译工作由[testerhome](http://testerhome.com/topics/150)在推动, 我们会不断补充更多的文档和测试用例.
+欢迎对Appium感兴趣的同学加入我们, 为开源社区贡献中国人的力量.
+
diff --git a/docs/cn/android-hax-emulator.cn.md b/docs/cn/android-hax-emulator.cn.md
@@ -0,0 +1,11 @@
+# Intel® 硬件加速器管理
+
+如果你发现android虚拟机太慢, 并且你的系统运行在Intel® 的cpu上. 那么你可以尝试下HAXM, HAXM能够让你充分利用硬件虚拟化技术来加速android模拟器
+
+* 要安装HAXM, 你可以打开Android SDK Manager, 你可以在Extras中发现这个安装选项
+
+* 你可以在[Inter官方网站][1]找到所有相关的文档
+* 这将需要x86的模拟镜像
+
+[1]: http://software.intel.com/en-us/articles/intel-hardware-accelerated-execution-manager/ "Hax" 
+[2]: http://software.intel.com/en-us/search/site/language/en?query=Intel%20Hardware%20Accelerated%20Execution%20Manager%20%28HAXM%29 "Hax all"
diff --git a/docs/cn/caps.cn.md b/docs/cn/caps.cn.md
@@ -0,0 +1,21 @@
+Appium 服务关键字
+==========
+
+|关键字|描述|实例|
+|----|-----------|-------|
+|`app`|`.ipa` or `.apk`文件所在的本地绝对路径或者远程路径,也可以是一个包括两者的`.zip`. Appium会先尝试安装路径对应的应用在适当的真机或模拟器上.也可以是一个`chrome`或者`chromium`，这样就会在android系统中其中chrome或chromium,也可以是`safari`会启动ios上的safari. 针对Android系统，如果你指定`app-package`和`app-activity`(具体见下面)的话，那么就可以不指定`app`.|比如`/abs/path/to/my.apk`或`http://myapp.com/app.ipa`, Android上的`chrome`, `chromium`, iOS的`safari`|
+|`browserName`|要启动的浏览器的名称|比如`chrome`和`safari`|
+|`device`|要使用的模拟器或真机的类型名称|比如`ios`, `selendroid`, `firefoxos`, `mock_ios`, `android` |
+|`version`|Android API版本, iOS版本, Chrome/Safari版本|比如6.1|
+
+--
+
+#### Android特有的
+
+|关键字|描述|实例|
+|----|-----------|-------|
+|`app-activity`| 你要启动的Android 应用对应的Activity名称|比如`MainActivity`, `.Settings`|
+|`app-package`| 你想运行的Android应用的包名|比如`com.example.android.myApp`, `com.android.settings`|
+|`app-wait-activity`| 你想要等待启动的Android Activity名称|比如`SplashActivity`|
+|`device-ready-timeout`| 设置一个模拟器或真机准备就绪的时间|比如`5`|
+|``compressXml``| 参考[setCompressedLayoutHeirarchy(true)](http://developer.android.com/tools/help/uiautomator/UiDevice.html#setCompressedLayoutHeirarchy(boolean\))| `true`|
diff --git a/docs/cn/finding-elements.cn.md b/docs/cn/finding-elements.cn.md
@@ -0,0 +1,165 @@
+元素定位与交互
+=====================================
+
+
+Appium支持一个Webdriver元素定位方法的子集
+
+* find by "tag name" (i.e., 通过UI的控件类型)
+* find by "name" (i.e., 通过元素的文本, 标签, 或者开发同学添加的id标示, 比如accessibilityIdentifier)
+* find by "xpath" (i.e., 具有一定约束的路径抽象标示, 基于XPath方式)
+
+###标签名抽象映射
+
+你可以使用UIAutomation的控件类型用于标签名, 或者使用简化的映射, 可以参考下如下例子
+https://github.com/appium/appium/blob/master/lib/uiauto/lib/mechanic.js#L29
+
+(官方文档外的补充)
+对于Android下的元素对应, 可以参考
+https://github.com/appium/appium/blob/master/lib/devices/android/bootstrap/src/io/appium/android/bootstrap/AndroidElementClassMap.java
+
+例子
+--------
+
+### 找到屏幕上所有的UIAButtons
+
+WD.js:
+
+```js
+driver.elementsByTagName('button', function(err, buttons) {
+  // tap all the buttons
+  var tapNextButton = function() {
+    var button = buttons.shift();
+    if (typeof button !== "undefined") {
+      button.click(function(err) {
+        tapNextButton();
+      })
+    } else {
+      driver.quit();
+    }
+  }
+  tapNextButton();
+});
+```
+
+Ruby:
+
+```ruby
+buttons = @driver.find_elements :tag_name, :button
+buttons.each { |b| b.click }
+```
+
+Python:
+
+```python
+[button.click() for button in driver.find_elements_by_tag_name('button')]
+```
+
+### 找到所有文本内容(或者accessibilityIdentifier)为"Go"的元素
+
+WD.js:
+
+```js
+driver.elementByName('Go', function(err, el) {
+  el.tap(function(err) {
+    driver.quit();
+  });
+});
+```
+
+Ruby:
+
+```ruby
+@driver.find_element(:name, 'Go').click
+```
+Python:
+
+```python
+driver.find_element_by_name('Go').click()
+```
+
+### 找到以"Hi, "开头的导航条元素
+
+WD.js:
+
+```js
+driver.elementByXpath('//navigationBar/text[contains(@value, "Hi, ")]', function(err, el) {
+  el.text(function(err, text) {
+    console.log(text);
+    driver.quit();
+  });
+});
+```
+
+Ruby:
+
+```ruby
+@driver.find_element :xpath, '//navigationBar/text[contains(@value, "Hi, ")]'
+```
+
+### 通过tagName查找元素
+
+Java:
+
+```java
+driver.findElement(By.tagName("button")).sendKeys("Hi");
+
+WebELement element = findElement(By.tagName("button"));
+element.sendKeys("Hi");
+
+List<WebElement> elems = findElements(By.tagName("button"));
+elems.get(0).sendKeys("Hi");
+```
+
+Python:
+
+```python
+driver.find_elements_by_tag_name('tableCell')[5].click()
+```
+
+# FindAndAct<a name="findandact"></a>
+
+你也可以通过一行命令来完成元素的查找和交互(只适用于IOS)
+举个例子, 你可以通过一次调用来实现查找一个元素并点击它, 使用的命令是`mobile: findAndAct`
+
+Python:
+
+```python
+args = {'strategy': 'tag_name', 'selector': 'button', 'action': 'tap'}
+driver.execute_script("mobile: findAndAct", args)
+```
+
+### 用一个滑动手势进行下拉刷新
+
+Python:
+
+```python
+js_snippet = "mobile: swipe"
+args = {'startX':0.5, 'startY':0.2, 'startX':0.5, 'startY':0.95, 'tapCount':1, 'duration':10}
+driver.execute_script(js_snippet, args)
+```
+
+备注:  driver.execute_script() 可以在 [Automating Mobile Gestures: Alternative access method](https://github.com/appium/appium/wiki/Automating-mobile-gestures)) 找到说明
+
+使用Appium Inspector来定位元素
+--------
+
+(翻译备注: 这个工具目前只有Mac版本, 如果你使用的是windows, 可以使用android自带的traceview工具来获得元素的位置)
+
+Appium提供了一个灵活的工具Appium Inspector, 允许你在app运行的时候, 直接定位你正在关注的元素. 通过Appium Inspector(靠近start test按钮的i标示文本), 你可以通过点击预览窗口上的控件来获得它的name属性, 或者直接在UI导航窗口中定位
+
+### 概述
+
+Appium Inspector有一个简单的布局, 全部由如下窗口组成.
+UI导航器, 预览, 录制与刷新按钮, 和交互工具
+
+![Step 1](https://raw.github.com/appium/appium/master/assets/InspectorImages/Overview.png)
+
+### 例子
+
+启动Appium Inspector后, (通过点击app右上的小"i"按钮), 你可以定位任何预览窗口中的元素. 作为测试, 我正在查找id为"show alert"的按钮
+
+![Step 1](https://raw.github.com/appium/appium/master/assets/InspectorImages/Step1.png)
+
+要找到这个按钮的id, 在定位预览窗口中我点击了"show alert"按钮, Appium Inspector在UI导航窗口中高亮显示了这个元素, 然后展示了刚被点击按钮的id和元素类型
+
+![Step 1](https://raw.github.com/appium/appium/master/assets/InspectorImages/Step2.png)
diff --git a/docs/cn/ios-deploy.cn.md b/docs/cn/ios-deploy.cn.md
@@ -0,0 +1,64 @@
+部署ios app 到手机上
+=====================================
+准备在真机上执行appium测试, 需要如下准备:
+
+1. 用特殊的设备参数来构建app
+1. 使用 [fruitstrap](https://github.com/ghughes/fruitstrap), 一个第三方程序，来部署你构建的app到手机上
+
+## Xcodebuild 命令的参数:
+新的参数运行指定设置. 参考 [developer.apple.com](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/xcodebuild.1.html):
+
+```
+xcodebuild [-project projectname] [-target targetname ...]
+             [-configuration configurationname] [-sdk [sdkfullpath | sdkname]]
+             [buildaction ...] [setting=value ...] [-userdefault=value ...]
+```
+
+这有一个资料来参考可用的[设置](https://developer.apple.com/library/mac/#documentation/DeveloperTools/Reference/XcodeBuildSettingRef/1-Build_Setting_Reference/build_setting_ref.html#//apple_ref/doc/uid/TP40003931-CH3-DontLinkElementID_10)
+
+```
+CODE_SIGN_IDENTITY (Code Signing Identity)
+    介绍: 标识符，指定一个签名.
+    例如: iPhone Developer
+```
+
+PROVISIONING_PROFILE 已经从可用的的命令中消失了，但还是有必要设置的。
+
+在xcodebuild命令中设置 "CODE_SIGN_IDENTITY" & "PROVISIONING_PROFILE":
+
+```
+xcodebuild -sdk <iphoneos> -target <target_name> -configuration <Debug> CODE_SIGN_IDENTITY="iPhone Developer: Mister Smith" PROVISIONING_PROFILE="XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX"
+```
+成功的话, app会构建到如下目录 ```<app_dir>/build/<configuration>-iphoneos/<app_name>.app```
+
+## 用Fruitstrap进行部署
+clone一个fruitstrap的fork版本在[ghughes version](https://github.com/ghughes/fruitstrap) ，这个已经不再维护. 已确认该fork可用[unprompted fork](https://github.com/unprompted/fruitstrap), 但是其它的据说也可用.
+
+clone成功的话, 执行 ``make fruitstrap``
+然后, 然后复制生成的 ``fruitstrap``到app的所在的目录或上级目录下。
+
+运行fruitstrap 通过输入以下命令 (命令是否可用依赖于你fork的 fruitstrap):
+```
+./fruitstrap -d -b <PATH_TO_APP> -i <Device_UDID>
+```
+如果是为了持续集成,你可以发现很有用的方法来记录fruitstrap命令行和日志文件中的记录, 像这样:
+```
+./fruitstrap -d -b <PATH_TO_APP> -i <Device_UDID> 2>&1 | tee fruit.out
+```
+在node服务启动前fruitstrap进行需要被结束, 一个方法是扫描fruitstrap的输出来得知app完成启动。 有一个有效的方法是通过一个Rakefile 和一个 ``go_device.sh`` 脚本:
+```
+bundle exec rake ci:fruit_deploy_app | while read line ; do 
+   echo "$line" | grep "text to identify successful launch" 
+   if [ $? = 0 ] 
+   then 
+   # Actions 
+       echo "App finished launching: $line" 
+       sleep 5 
+       kill -9 `ps -aef | grep fruitstrap | grep -v grep | awk '{print $2}'` 
+   fi
+ done
+```
+一旦fruitstrap的进程被结束, node 服务就可以启动并且appium测试可以被执行!
+
+下一步:
+[在真机上运行appium](https://github.com/appium/appium/wiki/Running-Appium-on-Real-Devices)