Permalink
Browse files

basic refresh of docs, just small edits for accuracy and completeness

  • Loading branch information...
1 parent 8a2af09 commit d28724cad97149bff9347dc77d080b529e1dc726 @jlipps jlipps committed Oct 25, 2016
View
@@ -10,15 +10,14 @@
[![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
* iOS
* Android
* Windows
-* FirefoxOS
See the [platform support doc](/docs/en/appium-setup/platform-support.md) for more detailed information.
@@ -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)
* [osx](/docs/en/appium-setup/running-on-osx.md)
* [windows](/docs/en/appium-setup/running-on-windows.md)
-
+
#### Windows Requirements
* Windows 10
* [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
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!
@@ -99,7 +94,14 @@ $ npm install -g 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/)
* Run it!
@@ -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).
+(*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.
You find elements by using a subset of WebDriver's element-finding strategies.
@@ -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
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
-[Dan Cuellar's](http://github.com/penguinho) work on iOS Auto.
+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.
+
+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
[Selendroid](http://github.com/DominikDary/selendroid) for older Android platforms.
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
Please take a look at our [contribution documentation](CONTRIBUTING.md)
@@ -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)
-### 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!
@@ -1,13 +1,6 @@
## Introduction to Appium
-Appium is an open-source tool for automating native,
-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.
+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.
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.
@@ -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
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 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,
the [WebDriver](http://docs.seleniumhq.org/projects/webdriver/) API.
@@ -31,18 +31,18 @@ Here are the steps required to talk to a web view in your Appium test:
// javascript
// assuming we have an initialized `driver` object for an app
driver
- .contexts().then(function (contexts) { // get list of available views. Returns array: ["NATIVE_APP","WEBVIEW_1"]
- return driver.context(contexts[1]); // choose the webview context
- })
+ .contexts().then(function (contexts) { // get list of available views. Returns array: ["NATIVE_APP","WEBVIEW_1"]
+ return driver.context(contexts[1]); // choose the webview context
+ })
- // do some web testing
- .elementsByCss('.green_button').click()
+ // do some web testing
+ .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
@@ -52,7 +52,7 @@ driver = new AppiumDriver(new URL("http://127.0.0.1:4723/wd/hub"), capabilities)
Set<String> contextNames = driver.getContextHandles();
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
@@ -76,18 +76,18 @@ driver.quit();
# Then switch to it using @driver.switch_to.context("WEBVIEW_6")
Given(/^I switch to webview$/) do
- webview = @driver.contexts.last
- @driver.switch_to.context(webview)
+ webview = @driver.contexts.last
+ @driver.switch_to.context(webview)
end
Given(/^I switch out of webview$/) do
- @driver.switch_to.context(@driver.contexts.first)
+ @driver.switch_to.context(@driver.contexts.first)
end
# Now you can use CSS to select an element inside your webview
And(/^I click a webview button $/) do
- @driver.find_element(:css, ".green_button").click
+ @driver.find_element(:css, ".green_button").click
end
```
@@ -116,23 +116,23 @@ driver.quit()
public function testThings()
{
- $expected_contexts = array(
- 0 => 'NATIVE_APP',
- 1 => 'WEBVIEW_1'
- );
+ $expected_contexts = array(
+ 0 => 'NATIVE_APP',
+ 1 => 'WEBVIEW_1'
+ );
- $contexts = $this->contexts();
- $this->assertEquals($expected_contexts, $contexts);
+ $contexts = $this->contexts();
+ $this->assertEquals($expected_contexts, $contexts);
- $this->context($contexts[1]);
- $context = $this->context();
- $this->assertEquals('WEBVIEW_1', $context);
+ $this->context($contexts[1]);
+ $context = $this->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
}
```
@@ -50,12 +50,13 @@ Once installed you can start the proxy with the following command:
> 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
where needed. This is also optional and may help with recent devices:
``` center
# change the udid
+# note, this is run from an Appium repository
> ./bin/ios-webkit-debug-proxy-launcher.js -c 0e4b2f612b65e98c1d07d22ee08678130d345429:27753 -d
```
@@ -1,15 +1,14 @@
## 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
-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 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)
For enabling iwd for xcode >= 7,
-- Checkout [appium-instruments](https://github.com/appium/appium-instruments)
-- Run `xcode-iwd.sh` present in `<appium-instruments>/bin/`
+- Check out [appium-instruments](https://github.com/appium/appium-instruments)
+- 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>
```
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
@@ -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
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.
@@ -21,8 +21,8 @@ Settings are implemented via the following API endpoints:
```
{
settings: {
- ignoreUnimportantViews : true
- }
+ ignoreUnimportantViews : true
+ }
}
```
@@ -31,10 +31,12 @@ Settings are implemented via the following API endpoints:
>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
**"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.
@@ -1,12 +1,12 @@
## 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).
-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).
+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).
-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.)
@@ -16,13 +16,12 @@ shell startup:
export ANDROID_HOME="/usr/local/adt/sdk"
-Now you're set up to run Appium! If you're running Appium from source, run
-`npm install` from your Appium checkout to install all the
-dependencies.
+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
+dependencies.)
### 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
detects older versions, but there is some additional setup required if you're
running from source.
@@ -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
[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, or use any of the power commands.
-* Selendroid requires the following permission for your app:
+ 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 instrumenting your app:
`<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
@@ -1,6 +1,6 @@
## 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:
@@ -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`
-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.
### 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/).
Oops, something went wrong.

0 comments on commit d28724c

Please sign in to comment.