add troubleshooting.cn.md

add real-devices.cn.md
update the cn doc to the latest
add saucelabs-repository in pom.xml in testng example

docs/cn/README.md

@@ -33,6 +33,8 @@ Appium最终开启了跨平台原生移动自动化的可能.
 你的环境需要配置好运行测试相关的特定移动平台,下面列出相关的依赖平台
 如果你想通过`npm install`来运行appium, 为Appium研究和贡献力量.你需要[node.js and npm](http://nodejs.org) 0.8 或者更高版本 (`brew install node`).
 
+你可以使用 `appium-doctor` 来验证 Appium 的所有依赖。运行 `appium-doctor`，然后提供 `--ios` 或者 `--android` 参数来验证两个平台的依赖是否配置正确。如果从源代码运行，你可以使用 `bin/appium-doctor.js` 或者 `node bin/appium-doctor.js`
+
 ### IOS依赖
 
 * Mac OS X 10.7 or higher, 10.8.4 recommended

docs/cn/caps.cn.md

@@ -4,13 +4,15 @@ 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`|
+|`browserName`|考虑到Selenium的兼容性，必须要使用`''`;要启动的浏览器的名称|比如`chrome`和`safari`|
 |`device`|要使用的模拟器或真机的类型名称|比如`ios`, `selendroid`, `firefoxos`, `mock_ios`, `android` |
-|`version`|Android API版本, iOS版本, Chrome/Safari版本|比如6.1|
+|`version`|Android API版本, iOS版本, Chrome/Safari版本|(Android)4.2/4.3(ios) 6.0/6.1/7.0|
+|`newCommandTimeout`|设置在接受到有效命令之前结束进程并退出的时间|比如. `60`|
+|`launch`|在Appium已经安装的情况下可自动启动app。默认是`true`|`true`, `false`|
 
 --
 
-#### Android特有的
+#### Android特有
 
 |关键字|描述|实例|
 |----|-----------|-------|
@@ -19,3 +21,16 @@ Appium 服务关键字
 |`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`|
+
+--
+
+#### iOS特有
+
+|关键字|描述|实例|
+|----|-----------|-------|
+|`calendarFormat`| 为iOS的模拟器设置日历格式|比如. `gregorian`公历|
+|`deviceName`| iOS Simulator 的设备名|比如. `iPhone Retina (3.5-inch)`|
+|`language`| 为iOS的模拟器设置系统语言|比如. `fr`法语|
+|`launchTimeout`| 在Appium运行失败之前设置一个等待instruments的时间|比如. `20000`毫秒|
+|`locale`| 为iOS模拟器进行区域设置|比如. `fr_CA`法语|
+

docs/cn/real-devices.cn.md

@@ -0,0 +1,38 @@
+Appium在真机上
+======================
+Appium已经初步支持真机测试。
+
+如果要在真机上执行测试，你将要做如下准备：
+
+1.一个苹果的开发者ID和有效的开发者对应的配置文件和签名文件
+
+2.一台iPad或者iPhone
+
+3. 你要测试的应用的源码
+
+4. 一台安装了XCode和XCode Command Line Developer Tools的Mac机器 
+
+Provisioning Profile
+---
+要在真机上测试就需要一个有效的iOS开发者的Distribution Certificate and Provisioning Profile。你可以在这个上面找到配置这些的相关信息[Apple documentation](http://developer.apple.com/library/ios/#documentation/ToolsLanguages/Conceptual/YourFirstAppStoreSubmission/TestYourApponManyDevicesandiOSVersions/TestYourApponManyDevicesandiOSVersions.html)
+
+同样的，你还需要对你的应用签名，更多的信息可以查看[sign your app](http://developer.apple.com/library/ios/#documentation/ToolsLanguages/Conceptual/YourFirstAppStoreSubmission/ProvisionYourDevicesforDevelopment/ProvisionYourDevicesforDevelopment.html#//apple_ref/doc/uid/TP40011375-CH4-SW1).
+
+你必须使用Xcode的执行按钮来安装你的应用
+
+使用Appium运行你的测试
+---
+
+一旦你的设备和应用设置好了之后，你就能够用如下的命令在你的机器上执行测试：
+
+```
+node . -U <UDID> --app <bundle_id>
+```
+这将会启动Appium并且开始在真机上测试应用。
+
+疑问解答思路
+---
+0. 确认UDID已经正确的在xcode organizar或itunes中设置了。很长的字符串（20多个字符串）
+0.确认你测试代码中的测试对象设备的设置
+0. 再次确认你从instruments启动你的自动化测试
+0. 确认instruments已经关闭

docs/cn/troubleshooting.cn.md

@@ -0,0 +1,83 @@
+Appium 故障调试
+
+======================
+如果你遇到问题，先不要提交 ticket 到 github 或者发信去 appium-disscuss 邮件列表求教，这里教你如何处理。
+
+## 一般问题
+
+* 确保你是根据 [README](https://github.com/appium/appium/blob/master/docs/cn/README.md) 里面的入门指南按部就班的。
+* 确保你的系统配置好了(比如， xCode 是最新的，Android SDK 安装好了， `ANDROID_HOME` 配置好了，参照 [setup instructions](https://github.com/appium/appium/blob/master/docs/running-on-osx.md) ).
+* 确保你应用的路径正确。
+
+## 如果你从 Appium.app 运行的话 (通过 dmg 安装的)
+
+* 升级应用，然后重启。 如果你提示你无法升级，从[appium.io](http://appium.io)重新下载。
+
+## 如果你从源代码运行 Appium 的话
+
+* 在源代码目录下运行 `git pull` 确保你使用的是最新的代码。
+* 根据你想要自动化的平台运行 `reset.sh` :
+
+    ./reset.sh               # 所有平台
+    ./reset.sh --ios         # ios-only
+    ./reset.sh --android     # android-only
+    ./reset.sh --selendroid  # selendroid-only
+* 你可能会用到 `--dev`，如果你想下载和构建测试应用的话。
+* 你也能使用 `appium-doctor` 来自动验证所有依赖是否符合。如果从源代码运行，你可以使用`bin/appium-doctor.js` 或者 `node bin/appium-doctor.js`。
+* 如果你升级到 Android SDK 22，然后得到了如下错误：
+   `{ANDROID_HOME}/tools/ant/uibuild.xml:155: SDK does not have any Build Tools installed.`
+在 Android SDK 22 里，platform 和 build 工具被拆分到它们各自项中去。你需要确保安装了 build-tool 和 platform-tool。
+
+## Android
+
+* 确保 Android 模拟器启动并运行着。
+* 有时候需要运行 `adb kill-server && adb devices`。它可以帮助重置和Android设备之间的连接。
+* Make sure you know about the `app-package`, `app-activity`, and `app-wait-activity` desiredCapabilities (see [this doc](https://github.com/appium/appium/blob/master/docs/running-tests.md#run-android) for more information).
+* 你得知道 `app-package`， `app-activity` 和 `app-wait-activity` (详见 [文档](https://github.com/appium/appium/blob/master/docs/running-tests.md#run-android)).
+
+## IOS
+
+* 确保 Instruments.app 没打开。
+* If you're running the simulator, make sure your actual device is not plugged in
+* 如果你运行模拟器，确保没有连接真机。
+* 确保你的 Setting 里面 accessibility 辅助功能已经关闭 
+* 确保 APP 是为这个版本的模拟器编译的。
+* 如果你曾经用 sudo 运行过 Appium， 你需要先删除`/tmp/instruments_sock`， `sudo rm /tmp/instruments_sock`。然后不要使用 sudo 启动 Appium。
+* 如果你第一次运行 Appium，先授权使用 Instruments。通常会有一个对话框弹出让你输入你的密码。如果你从源代码运行 Appium，你只需简单的运行 `sudo grunt authorize`。如果用 npm 安装的话，运行 `sudo authorize_ios` 即可。
+* 如果你看到 `iOS Simulator failed to install the application.` 而且 App 的路径都正确的，那么重启下电脑看看。
+
+## Webview/Hybrid/Safari app 支持
+
+* 确保真机上的'Web Inspector'激活了。
+* 确保你激活了模拟器上的 Safari 的开发模式。Safari - Advance Preferences- Developer menu
+
+
+## FirefoxOS
+
+* 确保 Boot-to-Gecko 模拟器启动并运行着。
+* 确保模拟器的屏幕是亮着并没用锁屏的(可能需要重启 B2G).
+
+## 告诉社区
+
+如果你通过以上方法都不能解决问题，你可以做：
+
+如果你可以确认你发现的是个bug，来给我们报bug吧。[issue tracker](https://github.com/appium/appium/issues)
+
+如果你的 Appium 无法正常工作，然后错误信息不够清晰，欢迎加入[mailing list](https://groups.google.com/d/forum/appium-discuss)。 给大家发邮件询问，但是请包含以下信息：
+
+* 你是如何运行 Appium 的 (Appium.app, npm, source)
+* 客户端和服务端的错误信息
+* 除了上述， 贴出 Appium 服务器端的输出也非常重要，特别是运行在 verbose 模式。这样我们可以分析诊断问题在哪里。
+
+## Known Issues
+
+* 如果你从 Node 官网安装的 Node，那需要你使用 sudo 运行 npm。这其实并不好，试试看用 `brew install node`。
+* 使用 proxy，Webview 可以支持 iOS 真机。 见 [discussion](https://groups.google.com/d/msg/appium-discuss/u1ropm4OEbY/uJ3y422a5_kJ).
+* 有时候， iOS 的 UI 元素在定位到之后几毫秒会突然变得无效。这会导致一个类似`(null) cannot be tapped`的错误。唯一的解决方法就是把finding-and-acting的代码放到 retry 块里。参见 `mobile: findAndAct` [finding elements doc page](https://github.com/appium/appium/blob/master/docs/finding-elements.md)
+* 如果你通过 MacPorts 安装的 node 和 npm，那么确保 MacPorts 的 bin 文件夹 (`/opt/local/bin`) 被添加到环境变量 `PATH` 中去。
+
+## Specific Errors
+
+|Action|Error|Resolution|
+|------|-----|----------|
+|Running reset.sh|xcodebuild: error: SDK "iphonesimulator6.1" cannot be located|安装 iPhone 6.1 SDK 或者 使用单独的 SDK 构建 待测应用 比如： `grunt buildApp:UICatalog:iphonesimulator5.1`|

sample-code/examples/java/testng/pom.xml

@@ -62,5 +62,17 @@
         </plugins>
     </build>
 
+    <repositories>
+        <repository>
+            <id>saucelabs-repository</id>
+            <url>https://repository-saucelabs.forge.cloudbees.com/release</url>
+            <releases>
+                <enabled>true</enabled>
+            </releases>
+            <snapshots>
+                <enabled>true</enabled>
+            </snapshots>
+        </repository>
+    </repositories>
 
-</project>
+</project>

sample-code/examples/ruby/xunit_android.rb

@@ -28,7 +28,7 @@ def setup
 		@driver=init
 	end
 	def test_settings
-		#flick the screen until find the Aboud phone item 
+		#flick the screen until find the Aboud phone item
 		while @driver.find_elements(:xpath, '//text[@text="About phone"]').count==0
 			begin
 				@driver.execute_script 'mobile: flick', :startY=>0.9, :endY=>0.1