appium-setup docs

docs/en/appium-setup/real-devices.md

@@ -39,7 +39,7 @@ appium -U <udid> --app <path or bundle>
 
 This will start Appium and have Appium use the device to test the app.
 
-Refer to the [Appium server arguments](server-args.md) page for more detail on
+Refer to the [Appium server arguments](/docs/en/writing-running-appium/server-args.md) page for more detail on
 the arguments that you can use.
 
 ### Desired Capabilities
@@ -50,7 +50,7 @@ capabilities in your tests:
 * `app`
 * `udid`
 
-Refer to the [Appium server capabilities](caps.md) page for more detail on
+Refer to the [Appium server capabilities](docs/en/writing-running-appium/caps.md) page for more detail on
 the capabilities that you can use.
 
 ### Troubleshooting ideas
@@ -59,7 +59,7 @@ the capabilities that you can use.
    is a long string (20+ chars).
 0. Make sure that you can run your tests against the Simulator.
 0. Double check that you can invoke your automation from Instruments.
-0. Make sure Instruments in closed already.
+0. Make sure Instruments is not already running.
 
 ### Appium on real Android devices
 

docs/en/appium-setup/running-on-linux.md

@@ -12,9 +12,11 @@ To get started, you'll need to install node.js (v.0.10 or greater). Just
 follow the [instructions for your flavor of linux](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager).
 
 Once you've got node.js installed, install the [Android SDK](http://developer.android.com/sdk/index.html).
-You will need to run the 'android' tool (included in the SDK) and make sure
-you have an API Level 17 or greater API installed. You will also need Ant to
-build the bootstrap jar that Appium uses for testing Android.
+You will need to run the 'android' tool (included in the SDK, under the 'tools' directory).
+
+Run the 'android' tool and use it to install an API Level 17 or greater.
+
+You will also need [Apache Ant](http://ant.apache.org/) to build the bootstrap jar that Appium uses for running against Android simulators/devices.
 
 Finally, set `$ANDROID_HOME` to be your Android SDK path. If you unzipped the
 Android SDK to /usr/local/adt/, for example, you should add this to your
@@ -25,19 +27,26 @@ shell startup:
 Now that you're setup to run Appium, run `./reset.sh --android` from your
 Appium checkout to install all the dependencies.
 
+### Additional Setup for Older Versions of Android
+
+Appium uses, and comes prepackaged with, Selendroid for running Android versions 2.3 to 4.1.
+Appium switches to using Selendroid automatically when it detects older versions, but there is some additional setup required.
+
+* Make sure you have [Maven 3.1.1](http://maven.apache.org/download.cgi) or newer installed (`mvn`).
+* Run `./reset.sh --selendroid` from your Appium checkout
+
 ### Running Appium
 
 To run tests on Linux, you will need to have the Android Emulator booted and
 running an AVD with API Level 17 or greater. Then run Appium (`appium`) after
 installing via NPM, or `node .` in the source directory if running from source.
 
-See the [server documentation](server-args.md) for all the command line
-arguments.
+See the [server documentation](/docs/en/writing-running-appium/server-args.md) for all the command line arguments.
 
 ### Notes
 
 * There exists a hardware accelerated emulator for android, it has its own
   limitations. For more information you can check out this
-  [page](android-hax-emulator.md).
+  [page](/docs/en/appium-setup/android-hax-emulator.md).
 * Make sure that `hw.battery=yes` in your AVD's `config.ini`, if you want to
   run any of the Appium tests

docs/en/appium-setup/running-on-osx.md

@@ -5,10 +5,9 @@ Appium on OS X supports iOS and Android testing.
 ### System setup (iOS)
 
 * Appium requires Mac OS X 10.7, but 10.8 or 10.9 is recommended.
-* Make sure you have Xcode and the iOS SDK(s) installed. (Appium currently
-  supports Xcode 4.6.3 for iOS up to 6.1 and Xcode 5.x for iOS 7.0 and 7.1.
-  Note that testing against iOS versions below 7.0 using Xcode 5 is not
-  recommended. See the next section for more information.)
+* Make sure you have Xcode and the iOS SDK(s) installed. Xcode version 5.1 is
+  recommended as earlier versions of Xcode are limited in which version of iOS
+  they can test against. See the next section for more detail.
 * You need to authorize use of the iOS Simulator. If you are running Appium
   from NPM, you'll do this by running `sudo authorize_ios` (`authorize_ios` is
   a binary made available by the Appium npm package). If you're running Appium
@@ -18,10 +17,13 @@ Appium on OS X supports iOS and Android testing.
 
 ### Testing against multiple iOS SDKs
 
-Apple's `instruments` binary, which Appium uses to launch the iOS simulator, by
-default uses the currently-selected Xcode, and the highest iOS SDK installed
-with that version of Xcode. This means that if you want to test iOS 6.1, but
-have iOS 7.1 installed, Appium will be forced to use the 7.1 Simulator
+Xcode version 5.1 allows for automatic testing against iOS versions 6.0 and later.
+If using version 5.1, you can ignore the rest of this section.
+
+For Xcode 4.6.3 to 5.0, Apple's `instruments` binary, which Appium uses to launch
+the iOS simulator, by default uses the currently-selected Xcode, and the highest
+iOS SDK installed with that version of Xcode. This means that if you want to test
+iOS 6.1, but have iOS 7.1 installed, Appium will be forced to use the 7.1 Simulator
 regardless. The only way around this is to have multiple copies of Xcode
 installed with different sets of SDKs. You can then switch to the particular
 copy of Xcode that has the versions you want to test with before starting
@@ -30,7 +32,7 @@ Appium.
 In addition, it's been discovered that testing against iOS 6.1 with Xcode
 5 causes increased slowness and instability, so it's recommended that for
 testing against iOS 6.1 and below we use Xcode 4.6.3, and for testing against
-iOS 7.0 we use Xcode 5.We can do this by, say, having Xcode 5 at
+iOS 7.0 we use Xcode 5. We can do this by, say, having Xcode 5 at
 `/Applications/Xcode.app`, and Xcode 4.6 and `/Applications/Xcode-4.6.app`.
 Then we use the following command:
 
@@ -47,9 +49,9 @@ To go back to iOS 7.1 testing.
 * Make sure you have the
   [Android SDK installed](http://developer.android.com/sdk/index.html).
 * Make sure you have Android SDK API >= 17 installed. To do this, run the
-  Android SDK Manager (`android`) and select the API in the extra packages you
+  Android SDK Manager (`android` binary in the "tools" directory of the SDK) and select the API in the extra packages you
   can install.
-* Make sure you have `ant` installed. Ant is used to build the Appium bootstrap
+* Make sure you have `Apache Ant` installed. Ant is used to build the Appium bootstrap
   jar as well as the test applications. Mac OS X Mavericks no longer comes
   pre-packaged with `ant` so you will need to
   [download and install it](http://ant.apache.org/bindownload.cgi).
@@ -69,4 +71,4 @@ To go back to iOS 7.1 testing.
 * Make sure that `hw.battery=yes` in your AVD's `config.ini`.
 * There exists a hardware accelerated emulator for android, it has its own
   limitations. For more information you can check out this
-  [page](android-hax-emulator.md).
+  [page](/docs/en/appium-setup/android-hax-emulator.md).

docs/en/appium-setup/running-on-windows.md

@@ -16,42 +16,42 @@ To get started:
 1. Install [node.js](http://nodejs.org/download/) (v.0.10 or greater). Use the
    installer from nodejs.org.
 1. Install the [Android SDK](http://developer.android.com/sdk/index.html).
-   You will need to run the 'android' tool (included in the SDK) and make sure
+   You will need to run the 'android' tool (included in the SDK, in the `tools` folder) and make sure
    you have an API Level 17 or greater API installed. Set `ANDROID_HOME` to be
-   your Android SDK path and add the tools and platform-tools folders to your
+   your Android SDK path and add the `tools` and `platform-tools` folders to your
    PATH variable.
 1. Install the Java JDK and set `JAVA_HOME` to your JDK folder.
 1. Install [Apache Ant](http://ant.apache.org/bindownload.cgi) or use the one
    that comes with the Android Windows SDK in the eclipse\plugins folder. Be
-   sure to add the folder containing ant to your PATH variable.
+   sure to add the folder containing Ant to your PATH variable.
 1. Install [Apache Maven](http://maven.apache.org/download.cgi) and set the
-   M2HOME and M2 environment variables. Set M2HOME to the directory maven is
-   installed in, and set M2 to %M2HOME\bin. Add the path you used for M2 to
+   M2HOME and M2 environment variables. Set `M2HOME` to the directory maven is
+   installed in, and set `M2` to `%M2HOME\bin`. Add the path you used for `M2` to
    your PATH.
 1. Install [Git](http://git-scm.com/download/win) Be sure to install Git for
    windows to run in the regular command prompt.
 1. Install [cURL](http://curl.haxx.se/download.html).
 
-Now that you've downloaded everything, run:
+Now that you've downloaded everything, run the following .bat file in the folder where you installed appium:
 
     reset.bat
 
 ### Running Appium
 
 To run tests on Windows, you will need to have the Android Emulator booted or
  an Android Device connected that is running an AVD with API Level 17 or
- greater. Then run Appium on the command line using node.js:
+ greater. Then run Appium on the command line inside the folder where you installed appium, using node.js:
 
     node .
 
-See the [server documentation](server-args.md) for all the command line
+See the [server documentation](/docs/en/writing-running-appium/server-args.md) for all the command line
 arguments.
 
 ### Notes
 
-* You must supply the `--no-reset` and `--full-reset` flags currently for
+* You must supply the `--no-reset` and `--full-reset` flags for
   Android to work on Windows.
 * There exists a hardware accelerated emulator for Android, it has it's own
   limitations. For more information you can check out this
-  [page](android-hax-emulator.md).
+  [page](/docs/en/appium-setup/android-hax-emulator.md).
 * Make sure that `hw.battery=yes` in your AVD's `config.ini`.

docs/en/appium-setup/troubleshooting.md

@@ -1,14 +1,13 @@
 ## Troubleshooting Appium
 
 Here's what to do if you're experiencing problems, before you submit a ticket
-to github or write to the appium-discuss mailing list.
+to github or write to the [appium-discuss mailing list](https://groups.google.com/forum/#!forum/appium-discuss).
 
 ### General
 
-* Make sure you've followed the getting started steps in the [README](../../README.md)
+* Make sure you've followed the getting started steps in the [README](/README.md)
 * Make sure your system is set up appropriately (i.e., XCode is updated,
-  Android SDK is installed and `ANDROID_HOME` is set:
-  [setup instructions](running-on-osx.md)
+  Android SDK is installed and `ANDROID_HOME` is set.
 * Make sure the paths to your applications are correct
 
 ### If you're running Appium.app
@@ -22,10 +21,13 @@ to github or write to the appium-discuss mailing list.
 * Run the appropriate flavor of `reset.sh` based on what you're trying to
 automate:
 
-    ./reset.sh               # all
-    ./reset.sh --ios         # ios-only
-    ./reset.sh --android     # android-only
-    ./reset.sh --selendroid  # selendroid-only
+|command                  | explanation |
+|-------------------------|-------------|
+|./reset.sh               | # all |
+|./reset.sh --ios         | # ios-only |
+|./reset.sh --android     | # android-only |
+|./reset.sh --selendroid  | # selendroid-only |
+
 * You might also want to run `reset.sh` with the `--dev` flag if you want the
   test apps downloaded and built as well.
 * You can also use `appium-doctor` to automatically verify that all
@@ -70,6 +72,7 @@ own items in the SDK manager. Make sure you install the build-tools and platform
 * Make Sure you enable the 'Web Inspector' on the real device.
 * Make Sure you enable the Safari - Advance Preferences- Developer menu for
   simulators.
+* Make sure you are properly switching contexts using the `context` appium commands provided by your client library.
 * If you getting this error: select_port() failed, when trying to open the
   proxy, see this [discussion](https://groups.google.com/forum/#!topic/appium-discuss/tw2GaSN8WX0)
 
@@ -88,6 +91,9 @@ provides are not clear, join the [mailing list](https://groups.google.com/d/foru
 and send a message. Please include the following:
 
 * How you're running Appium (Appium.app, npm, source)
+* What operating system you are using
+* What device and version you are testing against (i.e. Android 4.4, or iOS 7.1)
+* Whether you are running against a real device or a simulator/emulator
 * The client-side and server-side errors you're getting (i.e.,
 "In Python this is the exception I get in my test script,
 and here's a link to a paste of the Appium server output)