mirror of
https://github.com/appium/appium.git
synced 2026-05-02 08:19:52 -05:00
Merge pull request #9203 from appium/jlipps-driver-docs
add uiautomator and uiautomator2 driver docs
This commit is contained in:
Jonathan Lipps
@@ -1,49 +0,0 @@
|
||||
## Android Setup
|
||||
|
||||
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).
|
||||
|
||||
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.)
|
||||
|
||||
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
|
||||
shell startup:
|
||||
|
||||
export ANDROID_HOME="/usr/local/adt/sdk"
|
||||
|
||||
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, 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.
|
||||
|
||||
* Make sure you have [Maven 3.1.1](http://maven.apache.org/download.cgi) or
|
||||
newer installed (`mvn`).
|
||||
|
||||
### Running Appium Android Tests
|
||||
|
||||
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](/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](/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. 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
|
||||
@@ -30,10 +30,12 @@ instructions.
|
||||
|
||||
### Android Support
|
||||
|
||||
See [Running on OS X: Android](running-on-osx.md),
|
||||
[Running on Windows](running-on-windows.md), or
|
||||
[Running on Linux](running-on-linux.md) for Android requirements and setup
|
||||
instructions.
|
||||
Android automation is supported with two drivers:
|
||||
|
||||
* The [UiAutomator2 Driver](/docs/en/drivers/android-uiautomator2.md)
|
||||
* The [UiAutomator Driver](/docs/en/drivers/android-uiautomator.md)
|
||||
|
||||
Please refer to these driver docs for setup instructions.
|
||||
|
||||
* Versions: 2.3 and up
|
||||
* Versions 2.3 through 4.2 are supported via Appium's bundled version of
|
||||
|
||||
@@ -1,12 +0,0 @@
|
||||
## Appium on Android Real Devices
|
||||
|
||||
Hooray! There is nothing extra to know about testing real Android devices: it
|
||||
works exactly the same as testing on emulators. Make sure that your device
|
||||
can connect to ADB and has Developer Mode enabled (the process for this differs
|
||||
for different vendors, so check their documentation). For testing Chrome on a real
|
||||
device, you are responsible for ensuring that Chrome of an appropriate version
|
||||
is installed.
|
||||
|
||||
Also, you will want to make sure that "Verify Apps" in settings is
|
||||
disabled/unchecked, otherwise it can prevent some of Appium's helper apps from
|
||||
launching and doing their job correctly.
|
||||
@@ -1,6 +0,0 @@
|
||||
## Appium Support for Real Device Testing
|
||||
|
||||
Appium has support for real mobile device testing.
|
||||
|
||||
* For **Android** testing, see the [Android real device documentation](real-devices-android.md)
|
||||
* For **iOS** testing, see the [iOS XCUITest real device documentation](/docs/en/drivers/ios-xcuitest-real-devices.md)
|
||||
@@ -1,12 +0,0 @@
|
||||
## Running Appium on Linux
|
||||
|
||||
### Limitations
|
||||
|
||||
If you are running Appium on Linux, you cannot use the prebuilt '.app',
|
||||
which is built for OS X only. Additionally, you will not be able to test iOS
|
||||
apps because Appium relies on OS X-only libraries to support iOS testing.
|
||||
|
||||
### Setup (Android)
|
||||
|
||||
Instructions for setting up Android and running tests on Linux are the same as
|
||||
those on Mac OS X. See the [Android setup docs](/docs/en/appium-setup/android-setup.md).
|
||||
@@ -21,6 +21,7 @@ For more information on using Appium for mac, checkout the [docs](https://github
|
||||
|
||||
### Testing Android App
|
||||
|
||||
Instructions for setting up Android and running tests on Mac OS X are the same as
|
||||
those on Linux. See the [Android setup docs](/docs/en/appium-setup/android-setup.md).
|
||||
Instructions for setting up Android and running tests on Mac OS X are the same
|
||||
as those on Linux. See the [UiAutomator2
|
||||
Driver](/docs/en/drivers/android-uiautomator2.md) for more information.
|
||||
|
||||
|
||||
@@ -19,12 +19,9 @@ To get started:
|
||||
|
||||
## Additional Setup for Android App Testing
|
||||
|
||||
1. Download the latest Java JDK [here](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) (accept the license agreement first). Set 'JAVA_HOME' to be your JDK path. The `bin` in that directory should be added to your PATH variable.
|
||||
2. Install the [Android SDK](http://developer.android.com/sdk/index.html). Set the `ANDROID_HOME` environment variable to be your Android SDK path and add the `tools` and `platform-tools` folders to your PATH variable.
|
||||
3. 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.
|
||||
4. Install [Apache Maven](http://maven.apache.org/download.cgi) and set the M2HOME and M2 environment variables. Set `M2_HOME` to the directory maven is installed in, and set `M2` to the `bin` in that directory. Add the path you used for `M2` to your PATH.
|
||||
5. 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 (via the `appium` command)
|
||||
6. Your test script should ensure that the `platformVersion` capability corresponds to the emulator or device version you are testing, and that the `app` capability is an absolute path to the .apk file of the Android app.
|
||||
Please follow the guide for the [UiAutomator2
|
||||
Driver](/docs/en/drivers/android-uiautomator2.md) to get going with Android
|
||||
testing.
|
||||
|
||||
## Additional Setup for Windows App Testing
|
||||
|
||||
@@ -37,8 +34,3 @@ To get started:
|
||||
See the [server documentation](/docs/en/writing-running-appium/server-args.md) for all the command line arguments.
|
||||
|
||||
* On Windows run Appium.exe as an administrator, or when running from source you need to run cmd as an administrator.
|
||||
* You must supply the `--no-reset` or `--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](/docs/en/appium-setup/android-hax-emulator.md).
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
## The UiAutomator Driver for Android
|
||||
|
||||
Appium's older support for automating Android apps is via the `UiAutomator`
|
||||
driver. _(New to Appium? Read our [introduction to Appium drivers](#TODO))_.
|
||||
This driver leverages Google's
|
||||
[UiAutomator](https://developer.android.com/training/testing/ui-automator.html)
|
||||
technology to launch automation sessions on a device.
|
||||
|
||||
Development of the UiAutomator driver happens at the
|
||||
[appium-android-driver](https://github.com/appium/appium-android-driver)
|
||||
repo.
|
||||
|
||||
We recommend you upgrade to the [UiAutomator2 Driver](android-uiautomator2.md)
|
||||
and use that driver instead, since this driver will not be supported moving
|
||||
forward.
|
||||
|
||||
### Requirements and Support
|
||||
|
||||
(In addition to Appium's [general requirements](#TODO))
|
||||
|
||||
* Java 7 installed and configured correctly for your platform
|
||||
* Mac, Windows, or Linux OS with the ability to run the Android SDK
|
||||
|
||||
### Usage
|
||||
|
||||
The way to start a session using the UiAutomator driver is to include the
|
||||
`platformName` [capability](#TODO) in your [new session request](#TODO), with
|
||||
the value `Android`. Of course, you must also include appropriate
|
||||
`platformVersion`, `deviceName`, and `app` capabilities, at a minimum. In the
|
||||
case of this driver, no `automationName` capability should be used.
|
||||
|
||||
### Capabilities
|
||||
|
||||
The UiAutomator driver supports a number of standard [Appium
|
||||
capabilities](/docs/en/writing-running-appium/caps.md), but has an additional
|
||||
set of capabilities that modulate the behavior of the driver. These can be
|
||||
found currently at [Android
|
||||
section](/docs/en/writing-running-appium/caps.md#android-only) of the
|
||||
aforementioned doc.
|
||||
|
||||
For web tests, to automate Chrome instead of your own application, leave the
|
||||
`app` capability empty and instead set the `browserName` capability to
|
||||
`Chrome`. Note that you are responsible for ensuring that Chrome is on the
|
||||
emulator/device, and that it is of a version compatible with Chromedriver.
|
||||
|
||||
|
||||
### Commands
|
||||
|
||||
To see the various commands Appium supports, and specifically for information
|
||||
on how the commands map to behaviors for the UiAutomator driver, see the [API
|
||||
Reference](#TODO).
|
||||
|
||||
|
||||
### Setup
|
||||
|
||||
Given that the setup instructions for this driver and the newer UiAutomator2
|
||||
Driver are identical, please refer to the system, emulator, and device setup
|
||||
instructions on the [UiAutomator2
|
||||
Driver](/docs/en/drivers/android-uiautomator2.md) doc.
|
||||
@@ -0,0 +1,138 @@
|
||||
## The UiAutomator2 Driver for Android
|
||||
|
||||
Appium's flagship support for automating Android apps is via the `UiAutomator2`
|
||||
driver. _(New to Appium? Read our [introduction to Appium drivers](#TODO))_.
|
||||
This driver leverages Google's
|
||||
[UiAutomator2](https://developer.android.com/training/testing/ui-automator.html)
|
||||
technology to facilitate automation on a device or emulator.
|
||||
|
||||
Development of the UiAutomator2 driver happens at the
|
||||
[appium-uiautomator2-driver](https://github.com/appium/appium-uiautomator2-driver)
|
||||
repo.
|
||||
|
||||
Older Android-based drivers include:
|
||||
* The [UiAutomator Driver](android-uiautomator.md)
|
||||
* The [Selendroid Driver](#TODO)
|
||||
|
||||
### Requirements and Support
|
||||
|
||||
(In addition to Appium's [general requirements](#TODO))
|
||||
|
||||
* Java 7 installed and configured correctly for your platform
|
||||
* Mac, Windows, or Linux OS with the ability to run the Android SDK
|
||||
|
||||
### Usage
|
||||
|
||||
The way to start a session using the UiAutomator2 driver is to include the
|
||||
`automationName` [capability](#TODO) in your [new session request](#TODO), with
|
||||
the value `UiAutomator2`. Of course, you must also include appropriate
|
||||
`platformName` (=`Android`), `platformVersion`, `deviceName`, and `app`
|
||||
capabilities, at a minimum.
|
||||
|
||||
### Capabilities
|
||||
|
||||
The UiAutomator2 driver supports a number of standard [Appium
|
||||
capabilities](/docs/en/writing-running-appium/caps.md), but has an additional
|
||||
set of capabilities that modulate the behavior of the driver. These can be
|
||||
found currently at [Android
|
||||
section](/docs/en/writing-running-appium/caps.md#android-only) of the
|
||||
aforementioned doc.
|
||||
|
||||
For web tests, to automate Chrome instead of your own application, leave the
|
||||
`app` capability empty and instead set the `browserName` capability to
|
||||
`Chrome`. Note that you are responsible for ensuring that Chrome is on the
|
||||
emulator/device, and that it is of a [version compatible with
|
||||
Chromedriver](/docs/en/advanced-concepts/chromedriver.md).
|
||||
|
||||
|
||||
### Commands
|
||||
|
||||
To see the various commands Appium supports, and specifically for information
|
||||
on how the commands map to behaviors for the UiAutomator2 driver, see the [API
|
||||
Reference](#TODO).
|
||||
|
||||
|
||||
### Basic Setup
|
||||
|
||||
1. Ensure that you have Appium's [general dependencies](#TODO) (e.g., Node
|
||||
& NPM) installed and configured.
|
||||
|
||||
1. Ensure that Java (the JDK, not just the JRE) is installed and Java binaries
|
||||
are added to your path. The instructions for this step differ for Mac/Linux
|
||||
and for Windows. Please consult platform-specific documentation, as this is
|
||||
a common task. An example of how to change the PATH on Windows is
|
||||
[here](https://www.java.com/en/download/help/path.xml).
|
||||
|
||||
1. Ensure that the `JAVA_HOME` environment variable is also set to the JDK
|
||||
path. For Mac/Linux, for example (the specifics of this path will vary
|
||||
greatly by system), put this in your login script:
|
||||
|
||||
```
|
||||
export JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk1.8.0_111.jdk/Contents/Home"
|
||||
```
|
||||
|
||||
On Windows, this will be done by setting the environment variable in the
|
||||
control panel, using the same strategy as for setting PATH above.
|
||||
|
||||
1. Install the [Android SDK](http://developer.android.com/sdk/index.html). The
|
||||
supported way of doing this nowadays is to use [Android
|
||||
Studio](https://developer.android.com/studio/index.html). Use the provided
|
||||
GUI to install the Android SDK to a path of your choosing.
|
||||
|
||||
1. Set the `ANDROID_HOME` environment variable to match this path. For example,
|
||||
if you installed the SDK to `/usr/local/adt`, then there will typically be
|
||||
a `sdk` folder inside of that which contains the SDK files. In that case, on
|
||||
Mac and Linux, add the following line to your login script (e.g.,
|
||||
`~/.bashrc`, `~/.bash_profile`, etc...):
|
||||
|
||||
```
|
||||
export ANDROID_HOME="/usr/local/adt/sdk"
|
||||
```
|
||||
|
||||
On Windows, follow the same steps as before to set the environment variable
|
||||
in the control panel.
|
||||
|
||||
1. Using the SDK manager, ensure you have installed the SDK for Android API
|
||||
levels you wish to automate (e.g., 24).
|
||||
|
||||
1. On Windows, ensure that you always run Appium in Administrator mode.
|
||||
|
||||
At this point, your general system setup is done. Follow the steps below based
|
||||
on whether you want to automate an emulator or a real device. In addition you
|
||||
will need your app's APK (preferably built in Debug mode), whose path or URL
|
||||
you will use as the value of the `app` capability when running your tests.
|
||||
|
||||
### Emulator Setup
|
||||
|
||||
To run tests on emulators, use the AVD Manager included with Android Studio or
|
||||
the SDK. With this tool, create the emulator that matches your needs. With the
|
||||
emulator launched, Appium will automatically find and use it for its tests.
|
||||
Otherwise, if you specify the `avd` capability with the value matching the name
|
||||
of your emulator, then Appium will attempt to launch the emulator for you.
|
||||
|
||||
Additional tips for emulators:
|
||||
|
||||
* There exists a hardware accelerated emulator for Android, though it has its
|
||||
own limitations. It can be installed from Intel's website, or through the
|
||||
Android SDK Manager. For more information, go
|
||||
[here](http://software.intel.com/en-us/articles/intel-hardware-accelerated-execution-manager/).
|
||||
* 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. (As of Android
|
||||
5.0, this is the default.)
|
||||
|
||||
### Real Device Setup
|
||||
|
||||
For Android automation, no additional setup is required for testing on real
|
||||
devices, other than these simple requirements:
|
||||
|
||||
* Ensure that [Developer
|
||||
mode](https://developer.android.com/studio/debug/dev-options.html) is turned
|
||||
on for the device.
|
||||
* Ensure that the device is connected via USB to the Appium host, and can be
|
||||
seen by [ADB](https://developer.android.com/studio/command-line/adb.html)
|
||||
(run `adb devices` to make sure).
|
||||
* Ensure that "Verify Apps" in settings is disabled, to allow Appium's helper
|
||||
apps to function without manual intervention.
|
||||
|
||||
(For some specific commands, the device might need to be rooted, though this is
|
||||
not the norm.)
|
||||
@@ -94,12 +94,8 @@ all set now!
|
||||
First, make sure you have one and only one Android emulator or device
|
||||
connected. If you run `adb devices`, for example, you should see one device
|
||||
connected. This is the device Appium will use for tests. Of course, to have
|
||||
a device connected, you'll need to have made an Android AVD (see system
|
||||
setup ([Windows](https://github.com/appium/appium/blob/master/docs/en/appium-setup/running-on-windows.md),
|
||||
[Mac](https://github.com/appium/appium/blob/master/docs/en/appium-setup/running-on-osx.md),
|
||||
or [Linux](https://github.com/appium/appium/blob/master/docs/en/appium-setup/running-on-linux.md))
|
||||
for more information). If the Android SDK tools are on your path, you can
|
||||
simply run:
|
||||
a device connected, you'll need to have made an Android AVD. If the Android SDK
|
||||
tools are on your path, you can simply run:
|
||||
|
||||
emulator -avd <MyAvdName>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user