From 116c62869d5eb0aeac73f9f0e63c428bdfb4269d Mon Sep 17 00:00:00 2001 From: Jonah Stiennon Date: Tue, 8 Jul 2014 12:25:01 -0700 Subject: [PATCH] appium-setup docs --- docs/en/appium-setup/real-devices.md | 6 ++--- docs/en/appium-setup/running-on-linux.md | 21 ++++++++++++----- docs/en/appium-setup/running-on-osx.md | 26 ++++++++++++---------- docs/en/appium-setup/running-on-windows.md | 20 ++++++++--------- docs/en/appium-setup/troubleshooting.md | 22 +++++++++++------- 5 files changed, 56 insertions(+), 39 deletions(-) diff --git a/docs/en/appium-setup/real-devices.md b/docs/en/appium-setup/real-devices.md index c60b45513..5c77953d8 100644 --- a/docs/en/appium-setup/real-devices.md +++ b/docs/en/appium-setup/real-devices.md @@ -39,7 +39,7 @@ appium -U --app 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 diff --git a/docs/en/appium-setup/running-on-linux.md b/docs/en/appium-setup/running-on-linux.md index 867921243..4c323e791 100644 --- a/docs/en/appium-setup/running-on-linux.md +++ b/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 diff --git a/docs/en/appium-setup/running-on-osx.md b/docs/en/appium-setup/running-on-osx.md index d1811b3a5..f342b16a2 100644 --- a/docs/en/appium-setup/running-on-osx.md +++ b/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). diff --git a/docs/en/appium-setup/running-on-windows.md b/docs/en/appium-setup/running-on-windows.md index 1646e5fa7..2518e24c8 100644 --- a/docs/en/appium-setup/running-on-windows.md +++ b/docs/en/appium-setup/running-on-windows.md @@ -16,23 +16,23 @@ 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 @@ -40,18 +40,18 @@ Now that you've downloaded everything, run: 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`. diff --git a/docs/en/appium-setup/troubleshooting.md b/docs/en/appium-setup/troubleshooting.md index b7ed8ac08..4613823b3 100644 --- a/docs/en/appium-setup/troubleshooting.md +++ b/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)