Skip to content

Commit

Permalink
basic refresh of docs, just small edits for accuracy and completeness
Browse files Browse the repository at this point in the history
  • Loading branch information
jlipps committed Oct 25, 2016
1 parent 8a2af09 commit d28724c
Show file tree
Hide file tree
Showing 21 changed files with 105 additions and 354 deletions.
36 changes: 19 additions & 17 deletions README.md
Expand Up @@ -10,15 +10,14 @@


[![Build Status](https://team-appium.ci.cloudbees.com/job/Appium/badge/icon)](https://team-appium.ci.cloudbees.com/job/Appium/) [![Build Status](https://team-appium.ci.cloudbees.com/job/Appium/badge/icon)](https://team-appium.ci.cloudbees.com/job/Appium/)


Appium is an open source, cross-platform test automation tool for native, hybrid and mobile web apps, tested on simulators (iOS, FirefoxOS), emulators (Android), and real devices (iOS, Android, Windows, FirefoxOS). Appium is an open source, cross-platform test automation tool for native, hybrid and mobile web apps, tested on simulators (iOS), emulators (Android), and real devices (iOS, Android, Windows).




### Supported Platforms ### Supported Platforms


* iOS * iOS
* Android * Android
* Windows * Windows
* FirefoxOS


See the [platform support doc](/docs/en/appium-setup/platform-support.md) for more detailed information. See the [platform support doc](/docs/en/appium-setup/platform-support.md) for more detailed information.


Expand Down Expand Up @@ -77,16 +76,12 @@ You also need to download the Appium client for your language so you can write t
* [linux](/docs/en/appium-setup/running-on-linux.md) * [linux](/docs/en/appium-setup/running-on-linux.md)
* [osx](/docs/en/appium-setup/running-on-osx.md) * [osx](/docs/en/appium-setup/running-on-osx.md)
* [windows](/docs/en/appium-setup/running-on-windows.md) * [windows](/docs/en/appium-setup/running-on-windows.md)

#### Windows Requirements #### Windows Requirements


* Windows 10 * Windows 10
* [Documentation](/docs/en/appium-setup/running-on-windows.md) * [Documentation](/docs/en/appium-setup/running-on-windows.md)


#### FirefoxOS Requirements

* [Firefox OS Simulator](https://developer.mozilla.org/en/docs/Tools/Firefox_OS_Simulator)

### Quick Start ### Quick Start


Kick up an Appium server, and then run a test written in your favorite [WebDriver](https://w3c.github.io/webdriver/webdriver-spec.html)-compatible language! Kick up an Appium server, and then run a test written in your favorite [WebDriver](https://w3c.github.io/webdriver/webdriver-spec.html)-compatible language!
Expand All @@ -99,7 +94,14 @@ $ npm install -g appium
$ appium $ appium
``` ```


#### Using the App As we said above, you may want to run `appium-doctor` to ensure your system is set up properly:

```
$ npm install -g appium-doctor
$ appium-doctor
```

#### Using the Appium Desktop App


* [Download the Appium app](https://bitbucket.org/appium/appium.app/downloads/) * [Download the Appium app](https://bitbucket.org/appium/appium.app/downloads/)
* Run it! * Run it!
Expand All @@ -108,6 +110,8 @@ $ appium


The main guide for getting started writing and running tests is [the running tests](/docs/en/writing-running-appium/running-tests.md) doc, which includes explanations for iOS, Android, and Android older devices. If you're interested in testing on physical hardware, you might be interested in our [real devices guide](/docs/en/appium-setup/real-devices.md). The main guide for getting started writing and running tests is [the running tests](/docs/en/writing-running-appium/running-tests.md) doc, which includes explanations for iOS, Android, and Android older devices. If you're interested in testing on physical hardware, you might be interested in our [real devices guide](/docs/en/appium-setup/real-devices.md).


(*Note*: If you're automating iOS 10+, be sure to check out our [XCUITest Migration Guide](/docs/en/advanced-concepts/migrating-to-xcuitest.md) since Apple's automation support has changed significantly since iOS 10, with corresponding changes in Appium).

Essentially, we support a subset of the [Selenium WebDriver JSON Wire Protocol](https://w3c.github.io/webdriver/webdriver-spec.html), and extend it so that you can specify mobile-targeted [desired capabilities](/docs/en/writing-running-appium/caps.md) to run your test through Appium. Essentially, we support a subset of the [Selenium WebDriver JSON Wire Protocol](https://w3c.github.io/webdriver/webdriver-spec.html), and extend it so that you can specify mobile-targeted [desired capabilities](/docs/en/writing-running-appium/caps.md) to run your test through Appium.


You find elements by using a subset of WebDriver's element-finding strategies. You find elements by using a subset of WebDriver's element-finding strategies.
Expand All @@ -124,18 +128,15 @@ For the full list of Appium doc pages, visit [this directory](/docs/en/).
Appium drives various native automation frameworks and provides an API based on Appium drives various native automation frameworks and provides an API based on
Selenium's [WebDriver JSON wire protocol](https://w3c.github.io/webdriver/webdriver-spec.html). Selenium's [WebDriver JSON wire protocol](https://w3c.github.io/webdriver/webdriver-spec.html).


Appium drives Apple's UIAutomation library for iOS support, which is based on For new iOS versions (9.3 and up), Appium drives Apple's XCUITest library. Our support for XCUITest utilizes Facebook's [WebDriverAgent](https://github.com/facebook/webdriveragent) project.
[Dan Cuellar's](http://github.com/penguinho) work on iOS Auto.
For older iOS versions (9.3 and below), Appium drives Apple's UIAutomation library, using a strategy which is based on [Dan Cuellar's](http://github.com/penguinho) work on iOS Auto.


Android support uses the UiAutomator framework for newer platforms and Android support uses the UiAutomator framework for newer platforms and
[Selendroid](http://github.com/DominikDary/selendroid) for older Android platforms. [Selendroid](http://github.com/DominikDary/selendroid) for older Android platforms.


Windows support uses Microsoft's [WinAppDriver](https://github.com/Microsoft/WinAppDriver) Windows support uses Microsoft's [WinAppDriver](https://github.com/Microsoft/WinAppDriver)


FirefoxOS support leverages [Marionette](https://developer.mozilla.org/en-US/docs/Marionette),
an automation driver that is compatible with WebDriver and is used to automate
Gecko-based platforms.

### Contributing ### Contributing


Please take a look at our [contribution documentation](CONTRIBUTING.md) Please take a look at our [contribution documentation](CONTRIBUTING.md)
Expand All @@ -145,11 +146,12 @@ for instructions on how to build, test and run Appium from source.


Interested in where Appium is heading in the future? Check out the [Roadmap](ROADMAP.md) Interested in where Appium is heading in the future? Check out the [Roadmap](ROADMAP.md)


### Project Credits & Inspiration ### Project History, Credits & Inspiration


[Credits](/docs/en/contributing-to-appium/credits.md) * [History](http://appium.io/history)
* [Credits](/docs/en/contributing-to-appium/credits.md)


### Mailing List ### User Forums


Announcements and debates often take place on the [Discussion Group](https://discuss.appium.io), be sure to sign up! Announcements and debates often take place on the [Discussion Group](https://discuss.appium.io), be sure to sign up!


Expand Down
14 changes: 4 additions & 10 deletions docs/en/about-appium/intro.md
@@ -1,13 +1,6 @@
## Introduction to Appium ## Introduction to Appium


Appium is an open-source tool for automating native, Appium is an open-source tool for automating native, mobile web, and hybrid applications on iOS mobile, Android mobile, and Windows desktop platforms. **Native apps** are those written using the iOS, Android, or Windows SDKs. **Mobile web apps** are web apps accessed using a mobile browser (Appium supports Safari on iOS and Chrome or the built-in 'Browser' app on Android). **Hybrid apps** have a wrapper around a "webview" -- a native control that enables interaction with web content. Projects like [Phonegap](http://phonegap.com/), make it easy to build apps using web technologies that are then bundled into a native wrapper, creating a hybrid app.
mobile web, and hybrid applications on iOS and Android platforms.
**Native apps** are those written using the iOS, Android, or Windows SDKs. **Mobile web apps** are web apps accessed using a mobile browser (Appium supports
Safari on iOS and Chrome or the built-in 'Browser' app on Android). **Hybrid apps** have a
wrapper around a "webview" -- a native control that enables interaction with
web content. Projects like [Phonegap](http://phonegap.com/),
make it easy to build apps using web technologies that are then bundled into
a native wrapper, creating a hybrid app.


Importantly, Appium is "cross-platform": it allows you to write tests against Importantly, Appium is "cross-platform": it allows you to write tests against
multiple platforms (iOS, Android, Windows), using the same API. This enables code reuse between iOS, Android, and Windows testsuites. multiple platforms (iOS, Android, Windows), using the same API. This enables code reuse between iOS, Android, and Windows testsuites.
Expand All @@ -31,10 +24,11 @@ meet requirement #1 by using vendor-provided automation frameworks under the
hood. That way, we don't need to compile in any Appium-specific or hood. That way, we don't need to compile in any Appium-specific or
third-party code or frameworks to your app. This means **you're testing the same app you're shipping**. The vendor-provided frameworks we use are: third-party code or frameworks to your app. This means **you're testing the same app you're shipping**. The vendor-provided frameworks we use are:


* iOS: Apple's [UIAutomation](https://developer.apple.com/library/ios/documentation/DeveloperTools/Reference/UIAutomationRef/) * iOS 9.3 and above: Apple's [XCUITest](https://developer.apple.com/reference/xctest)
* iOS 9.3 and lower: Apple's [UIAutomation](https://developer.apple.com/library/ios/documentation/DeveloperTools/Reference/UIAutomationRef/)
* Android 4.2+: Google's [UiAutomator](http://developer.android.com/tools/help/uiautomator/index.html) * Android 4.2+: Google's [UiAutomator](http://developer.android.com/tools/help/uiautomator/index.html)
* Android 2.3+: Google's [Instrumentation](http://developer.android.com/reference/android/app/Instrumentation.html). (Instrumentation support is provided by bundling a separate project, [Selendroid](http://selendroid.io)) * Android 2.3+: Google's [Instrumentation](http://developer.android.com/reference/android/app/Instrumentation.html). (Instrumentation support is provided by bundling a separate project, [Selendroid](http://selendroid.io))
* Windows: Microsoft's [WinAppDriver](http://github.com/microsoft/winappdriver) * Windows: Microsoft's [WinAppDriver](http://github.com/microsoft/winappdriver)


We meet requirement #2 by wrapping the vendor-provided frameworks in one API, We meet requirement #2 by wrapping the vendor-provided frameworks in one API,
the [WebDriver](http://docs.seleniumhq.org/projects/webdriver/) API. the [WebDriver](http://docs.seleniumhq.org/projects/webdriver/) API.
Expand Down
50 changes: 25 additions & 25 deletions docs/en/advanced-concepts/hybrid.md
Expand Up @@ -31,18 +31,18 @@ Here are the steps required to talk to a web view in your Appium test:
// javascript // javascript
// assuming we have an initialized `driver` object for an app // assuming we have an initialized `driver` object for an app
driver driver
.contexts().then(function (contexts) { // get list of available views. Returns array: ["NATIVE_APP","WEBVIEW_1"] .contexts().then(function (contexts) { // get list of available views. Returns array: ["NATIVE_APP","WEBVIEW_1"]
return driver.context(contexts[1]); // choose the webview context return driver.context(contexts[1]); // choose the webview context
}) })


// do some web testing // do some web testing
.elementsByCss('.green_button').click() .elementsByCss('.green_button').click()


.context('NATIVE_APP') // leave webview context .context('NATIVE_APP') // leave webview context


// do more native stuff here if we want // do more native stuff here if we want


.quit() // stop webdrivage .quit() // stop webdrivage
``` ```


```java ```java
Expand All @@ -52,7 +52,7 @@ driver = new AppiumDriver(new URL("http://127.0.0.1:4723/wd/hub"), capabilities)


Set<String> contextNames = driver.getContextHandles(); Set<String> contextNames = driver.getContextHandles();
for (String contextName : contextNames) { for (String contextName : contextNames) {
System.out.println(contextNames); //prints out something like NATIVE_APP \n WEBVIEW_1 System.out.println(contextNames); //prints out something like NATIVE_APP \n WEBVIEW_1
} }
driver.context(contextNames.toArray()[1]); // set context to WEBVIEW_1 driver.context(contextNames.toArray()[1]); // set context to WEBVIEW_1


Expand All @@ -76,18 +76,18 @@ driver.quit();
# Then switch to it using @driver.switch_to.context("WEBVIEW_6") # Then switch to it using @driver.switch_to.context("WEBVIEW_6")


Given(/^I switch to webview$/) do Given(/^I switch to webview$/) do
webview = @driver.contexts.last webview = @driver.contexts.last
@driver.switch_to.context(webview) @driver.switch_to.context(webview)
end end


Given(/^I switch out of webview$/) do Given(/^I switch out of webview$/) do
@driver.switch_to.context(@driver.contexts.first) @driver.switch_to.context(@driver.contexts.first)
end end


# Now you can use CSS to select an element inside your webview # Now you can use CSS to select an element inside your webview


And(/^I click a webview button $/) do And(/^I click a webview button $/) do
@driver.find_element(:css, ".green_button").click @driver.find_element(:css, ".green_button").click
end end
``` ```


Expand Down Expand Up @@ -116,23 +116,23 @@ driver.quit()


public function testThings() public function testThings()
{ {
$expected_contexts = array( $expected_contexts = array(
0 => 'NATIVE_APP', 0 => 'NATIVE_APP',
1 => 'WEBVIEW_1' 1 => 'WEBVIEW_1'
); );


$contexts = $this->contexts(); $contexts = $this->contexts();
$this->assertEquals($expected_contexts, $contexts); $this->assertEquals($expected_contexts, $contexts);


$this->context($contexts[1]); $this->context($contexts[1]);
$context = $this->context(); $context = $this->context();
$this->assertEquals('WEBVIEW_1', $context); $this->assertEquals('WEBVIEW_1', $context);


// do webby stuff // do webby stuff


$this->context('NATIVE_APP'); $this->context('NATIVE_APP');


// do mobile stuff // do mobile stuff
} }
``` ```


Expand Down
3 changes: 2 additions & 1 deletion docs/en/advanced-concepts/ios-webkit-debug-proxy.md
Expand Up @@ -50,12 +50,13 @@ Once installed you can start the proxy with the following command:
> ios_webkit_debug_proxy -c 0e4b2f612b65e98c1d07d22ee08678130d345429:27753 -d > ios_webkit_debug_proxy -c 0e4b2f612b65e98c1d07d22ee08678130d345429:27753 -d
``` ```


You may also use the ios-webkit-debug-proxy-launcher to launch the You may also use `ios-webkit-debug-proxy-launcher`, a small script included with the Appium codebase, to launch the
proxy. It monitors the proxy log for errors, and relaunch the proxy proxy. It monitors the proxy log for errors, and relaunch the proxy
where needed. This is also optional and may help with recent devices: where needed. This is also optional and may help with recent devices:


``` center ``` center
# change the udid # change the udid
# note, this is run from an Appium repository
> ./bin/ios-webkit-debug-proxy-launcher.js -c 0e4b2f612b65e98c1d07d22ee08678130d345429:27753 -d > ./bin/ios-webkit-debug-proxy-launcher.js -c 0e4b2f612b65e98c1d07d22ee08678130d345429:27753 -d
``` ```


Expand Down
9 changes: 4 additions & 5 deletions docs/en/advanced-concepts/iwd_xcode7.md
@@ -1,15 +1,14 @@
## Setting up instruments without delay (iwd) for xcode 7 and iOS >= 9.0 ## Setting up instruments without delay (iwd) for xcode 7 and iOS >= 9.0


For iOS >= 9.0 instruments without delay (iwd) does not work by passing binaries through For iOS >= 9.0 instruments without delay (iwd) does not work by passing binaries through the command line (appium does this under the hood for xcode < 7). See [iwd](https://github.com/lawrencelomax/instruments-without-delay/tree/xcode7-quirks#xcode-7--ios-9-support)
the command line (appium does this under the hood for xcode < 7). See [iwd](https://github.com/lawrencelomax/instruments-without-delay/tree/xcode7-quirks#xcode-7--ios-9-support)


For enabling iwd for xcode >= 7, For enabling iwd for xcode >= 7,
- Checkout [appium-instruments](https://github.com/appium/appium-instruments) - Check out [appium-instruments](https://github.com/appium/appium-instruments)
- Run `xcode-iwd.sh` present in `<appium-instruments>/bin/` - Run `xcode-iwd.sh` present in `<appium-instruments>/bin/`, with arguments as indicated below:


``` ```
sh <appium-instruments>/bin/xcode-iwd.sh <path to xcode> <path to appium-instruments> sh <appium-instruments>/bin/xcode-iwd.sh <path to xcode> <path to appium-instruments>
``` ```
eg. `sh ./bin/xcode-iwd.sh /Applications/Xcode.app /Users/xyz/appium-instruments/` eg. `sh ./bin/xcode-iwd.sh /Applications/Xcode.app /Users/xyz/appium-instruments/`


Note: iwd with xcode7 will only work for iOS >= 9.0, you can switch to older xcode for iOS < 9.0 Note: iwd with Xcode 7 will only work for iOS >= 9.0, you can switch to an older version of Xcode for iOS < 9.0
2 changes: 2 additions & 0 deletions docs/en/advanced-concepts/migrating-to-1-0.md
@@ -1,3 +1,5 @@
*This document is old, and only of interest for those migrating to Appium 1.x from an earlier version*

## Migrating your tests from Appium 0.18.x to Appium 1.x ## Migrating your tests from Appium 0.18.x to Appium 1.x


Appium 1.0 has removed a number of deprecated features from the previous versions. This guide will help you know what needs to change in your test suite to take advantage of Appium 1.0. Appium 1.0 has removed a number of deprecated features from the previous versions. This guide will help you know what needs to change in your test suite to take advantage of Appium 1.0.
Expand Down
8 changes: 5 additions & 3 deletions docs/en/advanced-concepts/settings.md
Expand Up @@ -21,8 +21,8 @@ Settings are implemented via the following API endpoints:
``` ```
{ {
settings: { settings: {
ignoreUnimportantViews : true ignoreUnimportantViews : true
} }
} }
``` ```


Expand All @@ -31,10 +31,12 @@ Settings are implemented via the following API endpoints:
>Returns a JSON hash of all the currently specified settings. >Returns a JSON hash of all the currently specified settings.
``` ```
{ {
ignoreUnimportantViews : true ignoreUnimportantViews : true
} }
``` ```


Note that the actual commands you would use in your test script differ based on the language; see the specific Appium client documention for more information.

### Supported Settings ### Supported Settings


**"ignoreUnimportantViews"** - Boolean which sets whether Android devices should use `setCompressedLayoutHeirarchy()` which ignores all views which are marked IMPORTANT_FOR_ACCESSIBILITY_NO or IMPORTANT_FOR_ACCESSIBILITY_AUTO (and have been deemed not important by the system), in an attempt to make things less confusing or faster. **"ignoreUnimportantViews"** - Boolean which sets whether Android devices should use `setCompressedLayoutHeirarchy()` which ignores all views which are marked IMPORTANT_FOR_ACCESSIBILITY_NO or IMPORTANT_FOR_ACCESSIBILITY_AUTO (and have been deemed not important by the system), in an attempt to make things less confusing or faster.
Expand Down
19 changes: 9 additions & 10 deletions docs/en/appium-setup/android-setup.md
@@ -1,12 +1,12 @@
## Android Setup ## Android Setup


To get started, you'll need to install node.js (v4 or greater). Just To get started, you'll need to install Node.js (v4 or greater). Just
follow the [instructions for your flavor of linux](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager). 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). 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, under the 'tools' directory). 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. Run the `android` tool and use it to install an API Level 17 or greater.


(If you want to run Appium from source, you will also need [Apache Ant](http://ant.apache.org/) to build the bootstrap jar that Appium uses for running against Android simulators/devices.) (If you want to run Appium from source, you will also need [Apache Ant](http://ant.apache.org/) to build the bootstrap jar that Appium uses for running against Android simulators/devices.)


Expand All @@ -16,13 +16,12 @@ shell startup:


export ANDROID_HOME="/usr/local/adt/sdk" export ANDROID_HOME="/usr/local/adt/sdk"


Now you're set up to run Appium! If you're running Appium from source, run Now you're set up to run Appium! (If you're running Appium from source, make sure to run `npm install` from your Appium checkout to install all the
`npm install` from your Appium checkout to install all the dependencies.)
dependencies.


### Additional Setup for Older Versions of Android ### Additional Setup for Older Versions of Android


Appium uses, and comes prepackaged with, Selendroid for running Android Appium uses, and comes prepackaged with, a project called [Selendroid](https://selendroid.io) for running Android
versions 2.3 to 4.1. Appium switches to using Selendroid automatically when it versions 2.3 to 4.1. Appium switches to using Selendroid automatically when it
detects older versions, but there is some additional setup required if you're detects older versions, but there is some additional setup required if you're
running from source. running from source.
Expand All @@ -44,7 +43,7 @@ See the [server documentation](/docs/en/writing-running-appium/server-args.md) f
limitations. For more information you can check out this limitations. For more information you can check out this
[page](/docs/en/appium-setup/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 * Make sure that `hw.battery=yes` in your AVD's `config.ini`, if you want to
run any of the Appium tests, or use any of the power commands. run any of the Appium tests, or use any of the power commands. As of Android 5.0, this is the default.
* Selendroid requires the following permission for your app: * Selendroid requires the following permission for instrumenting your app:
`<uses-permission android:name="android.**permission.INTERNET"/>`, `<uses-permission android:name="android.**permission.INTERNET"/>`,
please make sure your app has internet permission set when you are using selendroid or older versions of Android i.e. 2.3 to 4.1 please make sure your app has internet permission set when you are using selendroid or older versions of Android i.e. 2.3 to 4.1
6 changes: 3 additions & 3 deletions docs/en/appium-setup/parallel_tests.md
@@ -1,6 +1,6 @@
## Parallel Android Tests ## Parallel Android Tests


Appium provides a way for users to automate multiple Android sessions on a single machine. All it involves is starting multiple Appium servers with different flags. Appium provides a way for users to automate multiple Android sessions on a single machine. All it involves is starting multiple Appium servers with different flags.


The important flags for automating multiple Android sessions are: The important flags for automating multiple Android sessions are:


Expand All @@ -18,13 +18,13 @@ If we had two devices with the ID's 43364 and 32456, we would start two differen


`node . -p 4491 -bp 2252 -U 43364` `node . -p 4491 -bp 2252 -U 43364`


As long as your Appium and Appium bootstrap ports are between 0 and 65536, all they have to be is different so that two Appium servers aren't trying to listen on the same port. Be sure that your -u flag corresponds with the correct device ID. This is how Appium knows which device to communicate with, so it must be accurate. As long as your Appium and Appium bootstrap ports are between 0 and 65536, all they have to be is different so that two Appium servers aren't trying to listen on the same port. Be sure that your -u flag corresponds with the correct device ID. This is how Appium knows which device to communicate with, so it must be accurate.


If you are using chromedriver or selendroid, set a different port for each server. If you are using chromedriver or selendroid, set a different port for each server.


### Parallel iOS Tests ### Parallel iOS Tests


Unfortunately, running local parallel iOS tests aren't possible. Unlike Android, only one version of the iOS simulator can be launched at a time, making it run multiple tests at once. Unfortunately, running local parallel iOS tests isn't currently possible. Unlike Android, only one version of the iOS simulator can be launched at a time, making it run multiple tests at once.


If you do want to run parallel iOS tests, you need to use Sauce. Simply upload your Appium test to Sauce, and it can run as many parallel iOS or Android tests as your account allows. See more about running your tests on Sauce [here](https://docs.saucelabs.com/tutorials/appium/). If you do want to run parallel iOS tests, you need to use Sauce. Simply upload your Appium test to Sauce, and it can run as many parallel iOS or Android tests as your account allows. See more about running your tests on Sauce [here](https://docs.saucelabs.com/tutorials/appium/).


0 comments on commit d28724c

Please sign in to comment.