diff --git a/.travis.yml b/.travis.yml index cbc1b32b0..645e172fe 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,7 +13,6 @@ env: - HELPER=Nightmare - HELPER=SeleniumWebdriver - HELPER=WebDriverIO - - HELPER=Appium addons: apt: packages: diff --git a/docs/helpers/Appium.md b/docs/helpers/Appium.md index 63dd4bb15..ae936c9ae 100644 --- a/docs/helpers/Appium.md +++ b/docs/helpers/Appium.md @@ -1,912 +1,806 @@ -Appium helper is extends from WebriverIO. It's support all browser methods and also includes special methods for mobile apps testing. You can use this helper to test Web on desktop and mobile devices and mobile apps. +# Appium + +Appium helper extends [WebriverIO](http://codecept.io/helpers/WebDriverIO/) helper. + It supports all browser methods and also includes special methods for mobile apps testing. + You can use this helper to test Web on desktop and mobile devices and mobile apps. #### Appium Installation Appium is an open source test automation framework for use with native, hybrid and mobile web apps that implements the WebDriver protocol. It allows you to run Selenium tests on mobile devices and also test native, hybrid and mobile web apps. -1. Download and install [Appium](http://appium.io/) - - ``` - npm i -g appium - ``` -2. Download and install Android SDK or Android Studio to manage emulators from [Android Studio site](https://developer.android.com/studio/index.html#downloads) -3. Set the $ANDROID_HOME env variable to your Android SDK path - - Example: - ``` - export ANDROID_HOME=/Users/bestUser/Library/Android/sdk - ``` -4. Add Android SDK tools to $PATH - - Example: - ``` - export PATH="${ANDROID_HOME}/tools:$PATH" - export PATH="${ANDROID_HOME}/tools/bin:$PATH" - ``` -5. Add Java Home bin directory to $PATH - - Example: - ``` - export PATH="${JAVA_HOME}/bin:$PATH" - ``` -6. Create and launch emulator: - - From Android Studio: - * Create any empty android application - * Create emulator using this [documentation](https://developer.android.com/studio/run/managing-avds.html) - * Note that x86 emulators works much faster as ARM emulators, but you can use them only on Mac and Linux. - * Launch emulator from interface - - From Command line: - * Create emulator using [avdmanager commandline tool](https://developer.android.com/studio/command-line/avdmanager.html) - * Launch emulator using [emulator commandline tool](https://developer.android.com/studio/run/emulator-commandline.html) -7. Test that Appium is installed correctly using `appium-doctor` - - ``` - npm i -g appium-doctor - appium-doctor - ``` - If there are any issues, you have to fix them before Appium launch - -8. Launch the daemon: `appium` -9. Also on Mac you can launch tests for iOS devices. For this, install xcode from App store. You can get detailed information [here](http://appium.io/slate/en/master/?ruby#running-appium-on-mac-os-x) +Download and install [Appium](http://appium.io/) + npm install -g appium +Launch the daemon: `appium` ### Configuration -This helper should be configured in codecept.conf.js +This helper should be configured in codecept.json or codecept.conf.js #### Appium configuration -- `port`: Appium server port +- `port`: Appium port - `restart`: restart browser or app between tests (default: true), if set to false cookies will be cleaned but browser window will be kept and for apps nothing will be changed. -- `desiredCapabilities`: Appium capabilities --- `platformName` - Which mobile OS platform to use --- `appPackage` - Java package of the Android app you want to run --- `appActivity` - Activity name for the Android activity you want to launch from your package. --- `deviceName`: The kind of mobile device or emulator to use --- `platformVersion`: Mobile OS version --- `app` - The absolute local path or remote http URL to an .ipa or .apk file, or a .zip containing one of these. Appium will attempt to install this app binary on the appropriate device first. --- `browserName`: Name of mobile web browser to automate. Should be an empty string if automating an app instead. +- `desiredCapabilities`: [], Appium capabilities, see below + - `platformName` - Which mobile OS platform to use + - `appPackage` - Java package of the Android app you want to run + - `appActivity` - Activity name for the Android activity you want to launch from your package. + - `deviceName`: The kind of mobile device or emulator to use + - `platformVersion`: Mobile OS version + - `app` - The absolute local path or remote http URL to an .ipa or .apk file, or a .zip containing one of these. Appium will attempt to install this app binary on the appropriate device first. + - `browserName`: Name of mobile web browser to automate. Should be an empty string if automating an app instead. Example: ```js - { - helpers: { - Appium: { - desiredCapabilities: { - platformName: "Android", - appPackage: "com.example.android.myApp", - appActivity: "MainActivity", - deviceName: "OnePlus3", - platformVersion: "6.0.1" - }, - port: 4723, - restart: false - } +{ + helpers: { + WebDriverIO: { + desiredCapabilities: { + platformName: "Android", + appPackage: "com.example.android.myApp", + appActivity: "MainActivity", + deviceName: "OnePlus3", + platformVersion: "6.0.1" + }, + port: 4723, + restart: false + } } - } +} ``` -Additional configuration params can be used from +Additional configuration params can be used from ## Access From Helpers Receive a Appium client from a custom helper by accessing `browser` property: ```js -this.helpers['Appium'].browser +let browser = this.helpers['Appium'].browser ``` **Parameters** -- `config` +- `config` -## _locate +## closeApp -Get elements by different locator types, including strict locator -Should be used in custom helpers: +Close the given application. ```js -this.helpers['Appium']._locate({name: 'password'}).then //... +I.closeApp(); ``` -**Parameters** +Appium: support only iOS -- `locator` +## constructor -## _locateCheckable +Appium Special Methods for Mobile only -Find a checkbox by providing human readable text: +**Parameters** -```js -this.helpers['Appium']._locateCheckable('I agree with terms and conditions').then // ... -``` +- `config` -**Parameters** +## grabAllContexts -- `locator` +Get list of all available contexts -## _locateClickable + let contexts = yield I.grabAllContexts(); -Find a clickable element by providing human readable text: +Appium: support Android and iOS + +## grabContext + +Retrieve current context ```js -this.helpers['Appium']._locateClickable('Next page').then // ... +let context = yield I.grabContext(); ``` -**Parameters** - -- `locator` +Appium: support Android and iOS -## _locateFields +## grabCurrentActivity -Find field elements by providing human readable text: +Get current device activity. ```js -this.helpers['Appium']._locateFields('Your email').then // ... +let activity = yield I.grabCurrentActivity(); ``` -**Parameters** - -- `locator` +Appium: support only Android -## acceptPopup +## grabNetworkConnection -Accepts the active JavaScript native popup window, as created by window.alert|window.confirm|window.prompt. -Don't confuse popups with modal windows, as created by [various libraries](http://jster.net/category/windows-modals-popups). +Get information about the current network connection (Data/WIFI/Airplane). +The actual server value will be a number. However WebdriverIO additional +properties to the response object to allow easier assertions. -Appium: support only web testing +```js +let con = yield I.grabNetworkConnection(); +``` -## amOnPage +Appium: support only Android -Opens a web page in a browser. Requires relative or absolute url. -If url starts with `/`, opens a web page of a site defined in `url` config parameter. +## grabOrientation -Appium: support only web testing +Get current orientation. ```js -I.amOnPage('/'); // opens main page of website -I.amOnPage('https://github.com'); // opens github -I.amOnPage('/login'); // opens a login page +let orientation = yield I.grabOrientation(); ``` -**Parameters** +Appium: support Android and iOS + +## grabSettings -- `url` url path or global url +Get all the currently specified settings. -## appendField +```js +let settings = yield I.grabSettings(); +``` -Appends text to a input field or textarea. -Field is located by name, label, CSS or XPath +Appium: support Android and iOS + +## hideDeviceKeyboard -Appium: support, but it's clear a field before insert in apps +Hide the keyboard. ```js -I.appendField('#myTextField', 'appended'); +// taps outside to hide keyboard per default +I.hideDeviceKeyboard(); +I.hideDeviceKeyboard('tapOutside'); + +// or by pressing key +I.hideDeviceKeyboard('pressKey', 'Done'); ``` **Parameters** -- `field` located by label|name|CSS|XPath|strict locator -- `value` text value - -## attachFile +- `strategy` desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)Appium: support Android and iOS +- `key` -Attaches a file to element located by label, name, CSS or XPath -Path to file is relative current codecept directory (where codecept.json is located). -File will be uploaded to remote system (if tests are running remotely). +## installApp -Appium: not tested +Install an app on device. ```js -I.attachFile('Avatar', 'data/avatar.jpg'); -I.attachFile('form input[name=avatar]', 'data/avatar.jpg'); +I.installApp('/path/to/file.apk'); ``` **Parameters** -- `locator` field located by label|name|CSS|XPath|strict locator -- `pathToFile` local file path relative to codecept.json config file +- `path` path to apk fileAppium: support only Android -## cancelPopup +## makeTouchAction -Dismisses the active JavaScript popup, as created by window.alert|window.confirm|window.prompt. +The Touch Action API provides the basis of all gestures that can be +automated in Appium. At its core is the ability to chain together ad hoc +individual actions, which will then be applied to an element in the +application on the device. +[See complete documentation](http://webdriver.io/api/mobile/touchAction.html) -Appium: support only web testing +```js +I.makeTouchAction("~buttonStartWebviewCD", 'tap'); +``` -## checkOption +Appium: support Android and iOS -Selects a checkbox or radio button. -Element is located by label or name or CSS or XPath. +**Parameters** + +- `locator` +- `action` -Appium: support only web testing +## openNotifications -The second parameter is a context (CSS or XPath locator) to narrow the search. +Open the notifications panel on the device. ```js -I.checkOption('#agree'); -I.checkOption('I Agree to Terms and Conditions'); -I.checkOption('agree', '//form'); +I.openNotifications(); ``` -**Parameters** - -- `field` checkbox located by label | name | CSS | XPath | strict locator -- `context` (optional) element located by CSS | XPath | strict locator - -## clearCookie +Appium: support only Android -Clears a cookie by name, -if none provided clears all cookies +## pullFile -Appium: support only web testing +Pulls a file from the device. ```js -I.clearCookie(); -I.clearCookie('test'); +I.pullFile('/storage/emulated/0/DCIM/logo.png', 'my/path'); +// save file to output dir +I.pullFile('/storage/emulated/0/DCIM/logo.png', output_dir); ``` -**Parameters** +Appium: support Android and iOS -- `cookie` (optional) +**Parameters** -## clearField +- `path` +- `dest` -Clears a `