diff --git a/docs/en/appium-clients.md b/docs/en/about-appium/appium-clients.md similarity index 91% rename from docs/en/appium-clients.md rename to docs/en/about-appium/appium-clients.md index fdc7c3e69..72636182a 100644 --- a/docs/en/appium-clients.md +++ b/docs/en/about-appium/appium-clients.md @@ -1,4 +1,4 @@ -# List of client libraries with Appium server support +## List of client libraries with Appium server support * [https://github.com/appium/ruby_lib](https://github.com/appium/ruby_lib) - Ruby * [https://github.com/appium/python-client](https://github.com/appium/python-client) - Python diff --git a/docs/en/intro.md b/docs/en/about-appium/intro.md similarity index 98% rename from docs/en/intro.md rename to docs/en/about-appium/intro.md index 1f11829d3..aabcc2a4e 100644 --- a/docs/en/intro.md +++ b/docs/en/about-appium/intro.md @@ -1,4 +1,4 @@ -# Introduction to Appium +## Introduction to Appium Appium is an open-source tool you can use to automate mobile native, mobile web, and mobile hybrid applications on iOS and Android platforms. @@ -17,7 +17,7 @@ or total amount of code reuse between iOS and Android testsuites. For specific information about what it means for Appium to "support" its platforms, version, and automation modalities, please see the [platform support doc](platform-support.md). -## Appium Philosophy +### Appium Philosophy Appium was designed to meet mobile automation needs according to a certain philosophy. The key points of this philosophy can be stated as 4 requirements: @@ -31,7 +31,7 @@ philosophy. The key points of this philosophy can be stated as 4 requirements: 4. A mobile automation framework should be open source, in spirit and practice as well as in name! -## Appium Design +### Appium Design So how does the structure of the Appium project live out this philosophy? We meet requirement #1 by using vendor-provided automation frameworks under the @@ -64,7 +64,7 @@ with extra API methods useful for mobile automation. It should be obvious that requirement #4 is a given -- you're reading this because [Appium is open source](https://github.com/appium/appium). -## Appium Concepts +### Appium Concepts **Client/Server Architecture**
Appium is at its heart a webserver that exposes a REST API. It receives @@ -114,7 +114,7 @@ so you don't need to worry about Node. They also come with an Inspector, which enables you to check out the hierarchy of your app. This can come in very handy when writing tests! -## Getting Started +### Getting Started Congratulations! You are now armed with enough knowledge to begin using Appium. Why not head back to the [getting started doc](../../README.md) for diff --git a/docs/en/grid.md b/docs/en/advanced-concepts/grid.md similarity index 96% rename from docs/en/grid.md rename to docs/en/advanced-concepts/grid.md index cd804fd48..e5bb935d9 100644 --- a/docs/en/grid.md +++ b/docs/en/advanced-concepts/grid.md @@ -1,4 +1,4 @@ -# Selenium Grid +## Selenium Grid You are able to register your appium server with a local grid by using the **"--nodeconfig"** server parameter. @@ -19,7 +19,7 @@ you will see your device on the grid console page: "http://**\**:**\**/grid/console" -## Grid Node Configuration Example json file +### Grid Node Configuration Example json file ```xml { diff --git a/docs/en/hybrid.md b/docs/en/advanced-concepts/hybrid.md similarity index 98% rename from docs/en/hybrid.md rename to docs/en/advanced-concepts/hybrid.md index 1898734f6..8e79c1ffe 100644 --- a/docs/en/hybrid.md +++ b/docs/en/advanced-concepts/hybrid.md @@ -1,4 +1,4 @@ -# Automating hybrid apps +## Automating hybrid apps One of the core principles of Appium is that you shouldn't have to change your app to test it. In line with that methodology, it is possible to test @@ -8,7 +8,7 @@ required so that Appium knows whether you want to automate the native aspects of the app or the web views, but thankfully, we can stay within the WebDriver protocol for everything. -## Automating hybrid iOS apps +### Automating hybrid iOS apps Here are the steps required to talk to a web view in your Appium test: @@ -28,7 +28,7 @@ Here are the steps required to talk to a web view in your Appium test: native portion of the app, simply call `context` again with the native context id to leave the web frame. -## Execution against a real iOS device +### Execution against a real iOS device To interact with a web view appium establishes a connection using a remote debugger. When executing the examples below against a @@ -220,7 +220,7 @@ class ContextTests extends PHPUnit_Extensions_AppiumTestCase } ``` -## Automating hybrid Android apps +### Automating hybrid Android apps Appium comes with built-in hybrid support via Chromedriver. Appium also uses Selendroid under the hood for webview support on devices older than 4.4. (In diff --git a/docs/en/migrating-to-1-0.md b/docs/en/advanced-concepts/migrating-to-1-0.md similarity index 94% rename from docs/en/migrating-to-1-0.md rename to docs/en/advanced-concepts/migrating-to-1-0.md index ee8cb8227..38230469a 100644 --- a/docs/en/migrating-to-1-0.md +++ b/docs/en/advanced-concepts/migrating-to-1-0.md @@ -1,8 +1,8 @@ -# 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. -## New client libraries +### New client libraries The biggest thing you need to worry about is using the new Appium client libraries instead of the vanilla WebDriver clients you are currently using. Visit the [Appium client list](appium-clients.md) to find the client for your language. Downloads and instructions for integrating into your code are available on the individual client websites. @@ -18,7 +18,7 @@ Instead of: from selenium import webdriver ``` -## New desired capabilities +### New desired capabilities The following capabilities are no longer used: @@ -36,7 +36,7 @@ The `app` capability remains the same, but now refers exclusively to non-browser We have also standardized on camelCase for Appium server caps. That means caps like `app-package` or `app-wait-activity` are now `appPackage` and `appWaitActivity` respectively. Of course, since Android app package and activity are now auto-detected, you should be able to omit them entirely in most cases. -## New locator strategies +### New locator strategies We've removed the following locator strategies: @@ -68,11 +68,11 @@ We've also added the following locator strategies: Refer to your client for ways to use these new locator strategies. -## XML, not JSON +### XML, not JSON App source methods, which previously returned JSON, now return XML, so if you have code that relies on parsing the app source, it will need to be updated. -## Hybrid support through context, not window +### Hybrid support through context, not window Hybrid apps were previously supported by switching between "windows" using @@ -100,12 +100,13 @@ And to switch between them, you use driver.switch_to.context("WEBVIEW") ``` + ```javascript // javascript driver.currentContext().then(function (context) { /*...*/ }) ``` -## No more `execute_script("mobile: xxx")` +### No more `execute_script("mobile: xxx")` All the `mobile: ` methods have been removed, and have been replaced by native methods in the Appium client libraries. This means that a method call like `driver.execute("mobile: lock", [5])` will now look something more like `driver.lock(5)` (where `lock` has been turned into a native client method). Of course, the details on calling these methods will differ by client. diff --git a/docs/en/android-hax-emulator.md b/docs/en/appium-setup/android-hax-emulator.md similarity index 92% rename from docs/en/android-hax-emulator.md rename to docs/en/appium-setup/android-hax-emulator.md index 6575b1e3d..1faa07cda 100644 --- a/docs/en/android-hax-emulator.md +++ b/docs/en/appium-setup/android-hax-emulator.md @@ -1,4 +1,4 @@ -# Intel® Hardware Accelerated Execution Manager +## Intel® Hardware Accelerated Execution Manager If you find the android emulator a slow and your system runs on an Intel® cpu, you can check out HAXM. HAXM let's you leverage your hardware for diff --git a/docs/en/ios-deploy.md b/docs/en/appium-setup/ios-deploy.md similarity index 89% rename from docs/en/ios-deploy.md rename to docs/en/appium-setup/ios-deploy.md index 92a2db6e1..4e61cd16e 100644 --- a/docs/en/ios-deploy.md +++ b/docs/en/appium-setup/ios-deploy.md @@ -1,4 +1,4 @@ -# Deploying your iOS app to your device +## Deploying your iOS app to your device To prepare for your Appium tests to run on a real device, you will need to: @@ -6,7 +6,7 @@ To prepare for your Appium tests to run on a real device, you will need to: 1. Use [fruitstrap](https://github.com/ghughes/fruitstrap), a 3rd-party tool, to deploy this build to your device -## Xcodebuild with parameters: +### Xcodebuild with parameters: A newer xcodebuild now allows settings to be specified. Taken from [developer.apple.com](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/xcodebuild.1.html): ``` @@ -35,7 +35,7 @@ xcodebuild -sdk -target -configuration CODE_SIG On success, the app will be built to your ```/build/-iphoneos/.app``` -## Deploy using Fruitstrap +### Deploy using Fruitstrap Go clone a forked version of fruitstrap as the [ghughes version](https://github.com/ghughes/fruitstrap) is no longer maintained. Success has been confirmed with the [unprompted fork](https://github.com/unprompted/fruitstrap), @@ -66,14 +66,14 @@ telling sign that the app has completed launching. This may prove useful if you are doing this via a Rakefile and a ``go_device.sh`` script: ``` -bundle exec rake ci:fruit_deploy_app | while read line ; do - echo "$line" | grep "text to identify successful launch" - if [ $? = 0 ] - then - # Actions - echo "App finished launching: $line" - sleep 5 - kill -9 `ps -aef | grep fruitstrap | grep -v grep | awk '{print $2}'` +bundle exec rake ci:fruit_deploy_app | while read line ; do + echo "$line" | grep "text to identify successful launch" + if [ $? = 0 ] + then + # Actions + echo "App finished launching: $line" + sleep 5 + kill -9 `ps -aef | grep fruitstrap | grep -v grep | awk '{print $2}'` fi done ``` diff --git a/docs/en/platform-support.md b/docs/en/appium-setup/platform-support.md similarity index 98% rename from docs/en/platform-support.md rename to docs/en/appium-setup/platform-support.md index 9be3e39ff..6fa854045 100644 --- a/docs/en/platform-support.md +++ b/docs/en/appium-setup/platform-support.md @@ -1,10 +1,10 @@ -# Appium Platform Support +## Appium Platform Support Appium supports a variety of platforms and testing modalities (native, hybrid, web, real devices, simulators, etc...). This document is designed to make explicit the level of support and requirements for each of these. -## iOS Support +### iOS Support See [Running on OS X: iOS](running-on-osx.md) for iOS requirements and setup instructions. @@ -28,7 +28,7 @@ instructions. set accessibility information on the control which enables some basic automation. -## Android Support +### Android Support See [Running on OS X: Android](running-on-osx.md), [Running on Windows](running-on-windows.md), or diff --git a/docs/en/real-devices.md b/docs/en/appium-setup/real-devices.md similarity index 92% rename from docs/en/real-devices.md rename to docs/en/appium-setup/real-devices.md index c38513f0e..6178a2307 100644 --- a/docs/en/real-devices.md +++ b/docs/en/appium-setup/real-devices.md @@ -1,4 +1,4 @@ -# Appium on real iOS devices +## Appium on real iOS devices Appium has support for real device testing. @@ -12,7 +12,7 @@ To get started on a real device, you will need the following: * A Mac with [Xcode](https://itunes.apple.com/en/app/xcode/id497799835?mt=12) and the Xcode Command Line Developer Tools. -## Provisioning Profile +### Provisioning Profile A valid iOS Development Distribution Certificate and Provisioning Profile are necessary to test on a real device. Your app will also need to be signed. You @@ -21,14 +21,14 @@ can find information about this in the [Apple documentation](https://developer.a Appium will attempt to install your app using Fruitstrap, but it is often easier to pre-install your app using Xcode to ensure there are no problems. -## Running your tests with Appium +### Running your tests with Appium Once your device and app are configured, you can run tests on that device by passing the `-U` or `--udid` flag to the server or the `udid` desired capability, and the bundle ID (if the app is installed on the device) or the path to the `.ipa` or `.apk` file via the `--app` flag or the `app` desired capability. -## Server Arguments +### Server Arguments For example, if you are prelaunching your app and wish for Appium to force use a specific UDID, then you may use the below command: @@ -42,7 +42,7 @@ 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 the arguments that you can use. -## Desired Capabilities +### Desired Capabilities You can launch the app on a device by including the following desired capabilities in your tests: @@ -53,7 +53,7 @@ capabilities in your tests: Refer to the [Appium server capabilities](caps.md) page for more detail on the capabilities that you can use. -## Troubleshooting ideas +### Troubleshooting ideas 0. Make sure UDID is correct by checking it in Xcode Organizer or iTunes. It is a long string (20+ chars). @@ -61,7 +61,7 @@ the capabilities that you can use. 0. Double check that you can invoke your automation from Instruments. 0. Make sure Instruments in closed already. -## Appium on real Android devices +### Appium on real Android devices Hooray! There's nothing extra to know about testing real Android devices: it works exactly the same as testing on emulators. Make sure that your device diff --git a/docs/en/running-on-linux.md b/docs/en/appium-setup/running-on-linux.md similarity index 95% rename from docs/en/running-on-linux.md rename to docs/en/appium-setup/running-on-linux.md index 8a7948234..2d2d25fc4 100644 --- a/docs/en/running-on-linux.md +++ b/docs/en/appium-setup/running-on-linux.md @@ -1,12 +1,12 @@ -# Running Appium on Linux +## Running Appium on Linux -## Limitations +### 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 +### Setup 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). @@ -25,7 +25,7 @@ shell startup: Now that you're setup to run Appium, run `./reset.sh --android` from your Appium checkout to install all the dependencies. -## Running Appium +### 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 on the command @@ -36,7 +36,7 @@ line using node.js: See the [server documentation](server-args.md) for all the command line arguments. -## Notes +### Notes * There exists a hardware accelerated emulator for android, it has it's own limitations. For more information you can check out this diff --git a/docs/en/running-on-osx.md b/docs/en/appium-setup/running-on-osx.md similarity index 96% rename from docs/en/running-on-osx.md rename to docs/en/appium-setup/running-on-osx.md index 6f65e1fe1..2e22bf38c 100644 --- a/docs/en/running-on-osx.md +++ b/docs/en/appium-setup/running-on-osx.md @@ -1,8 +1,8 @@ -# Running Appium on Mac OS X +## Running Appium on Mac OS X Appium on OS X supports iOS and Android testing. -## System setup (iOS) +### System setup (iOS) * Appium requires Mac OS X 10.7, but 10.8 is recommended. * Make sure you have Xcode and the iOS SDK(s) installed. (Appium currently @@ -16,7 +16,7 @@ Appium on OS X supports iOS and Android testing. are running [Appium.app](https://github.com/appium/appium-dot-app), you can authorize iOS through the GUI. -## Testing against multiple iOS SDKs +### 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 @@ -42,7 +42,7 @@ To prepare for iOS 6.1 testing. We run it again with a different Xcode: To go back to iOS 7.1 testing. -## System setup (Android) +### System setup (Android) * Make sure you have the [Android SDK installed](http://developer.android.com/sdk/index.html). diff --git a/docs/en/running-on-windows.md b/docs/en/appium-setup/running-on-windows.md similarity index 96% rename from docs/en/running-on-windows.md rename to docs/en/appium-setup/running-on-windows.md index 111d2b68f..1646e5fa7 100644 --- a/docs/en/running-on-windows.md +++ b/docs/en/appium-setup/running-on-windows.md @@ -1,6 +1,6 @@ -# Running Appium on Windows +## Running Appium on Windows -## Limitations +### Limitations If you are running Appium on Windows, you can use the [Appium.exe](https://github.com/appium/appium-dot-exe) client, which will allow @@ -9,7 +9,7 @@ able to test iOS apps on a locally hosted server, because Appium relies on OS X-only libraries to support iOS testing. You can however use the `Remote Server` option to connect to an Appium server running on a Mac. -## Setup +### Setup To get started: @@ -36,7 +36,7 @@ Now that you've downloaded everything, run: reset.bat -## Running Appium +### Running Appium 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 @@ -47,7 +47,7 @@ To run tests on Windows, you will need to have the Android Emulator booted or See the [server documentation](server-args.md) for all the command line arguments. -## Notes +### Notes * You must supply the `--no-reset` and `--full-reset` flags currently for Android to work on Windows. diff --git a/docs/en/troubleshooting.md b/docs/en/appium-setup/troubleshooting.md similarity index 94% rename from docs/en/troubleshooting.md rename to docs/en/appium-setup/troubleshooting.md index a255255b7..b962c1625 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/appium-setup/troubleshooting.md @@ -1,9 +1,9 @@ -# Troubleshooting Appium +## 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. -## General +### General * 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, @@ -11,17 +11,17 @@ to github or write to the appium-discuss mailing list. [setup instructions](running-on-osx.md) * Make sure the paths to your applications are correct -## If you're running Appium.app +### If you're running Appium.app * Update the app and restart. If you get a message saying the app can't be updated, re-download it from [appium.io](http://appium.io). -## If you're running Appium from source +### If you're running Appium from source * `git pull` to make sure you're running the latest code * 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 @@ -31,24 +31,24 @@ automate: * You can also use `appium-doctor` to automatically verify that all dependencies are met. If running from source, you may have to use `bin/appium-doctor.js` or `node bin/appium-doctor.js`. -* If you get this error after upgrading to Android SDK 22: +* If you get this error after upgrading to Android SDK 22: `{ANDROID_HOME}/tools/ant/uibuild.xml:155: SDK does not have any Build Tools installed.` In the Android SDK 22, the platform and build tools are split up into their own items in the SDK manager. Make sure you install the build-tools and platform-tools. -## Android +### Android * Make sure the Android emulator is up and running. * It's sometimes useful to run `adb kill-server && adb devices`. This can reset the connection to the Android device. * Make sure you set ANDROID_HOME pointing to the Android SDK directory -## IOS +### IOS * Make sure Instruments.app is not open * If you're running the simulator, make sure your actual device is not plugged in -* Make sure the accessibility helper is turned off in your Settings app +* Make sure the accessibility helper is turned off in your Settings app * Make sure the app is compiled for the version of the simulator that's being run * Make sure the app is compiled for the simulator (or real device) as @@ -65,7 +65,7 @@ own items in the SDK manager. Make sure you install the build-tools and platform * If you see `iOS Simulator failed to install the application.` and the paths are correct, try restarting the computer. -## Webview/Hybrid/Safari app support +### Webview/Hybrid/Safari app support * Make Sure you enable the 'Web Inspector' on the real device. * Make Sure you enable the Safari - Advance Preferences- Developer menu for @@ -73,12 +73,12 @@ own items in the SDK manager. Make sure you install the build-tools and platform * 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) -## FirefoxOS +### FirefoxOS * Make sure the Boot-to-Gecko simulator is up and running. * Make sure the simulator screen is alive and unlocked (might require restarting B2G). -## Let the community know +### Let the community know Once you've tried the above steps and your issue still isn't resolved, here's what you can do: @@ -97,7 +97,7 @@ and here's a link to a paste of the Appium server output) * Per above, it's very important to include a paste of the Appium server output when it's run in verbose mode so that we can diagnose what's going on. -## Known Issues +### Known Issues * If you've installed Node from the Node website, it requires that you use sudo for `npm`. This is not ideal. Try to get node with @@ -112,7 +112,7 @@ output when it's run in verbose mode so that we can diagnose what's going on. folder (`/opt/local/bin` by default) is added to `PATH` somewhere in your `~/.profile`, `~/.bash_profile` or `~/.bashrc`. -## Specific Errors +### Specific Errors |Action|Error|Resolution| |------|-----|----------| diff --git a/docs/en/credits.md b/docs/en/contributing-to-appium/credits.md similarity index 98% rename from docs/en/credits.md rename to docs/en/contributing-to-appium/credits.md index 98ecaa7c1..234ec9ec1 100644 --- a/docs/en/credits.md +++ b/docs/en/contributing-to-appium/credits.md @@ -1,4 +1,4 @@ -# Credits +## Credits ### These are the projects that inspired us, or are depended upon to make Appium awesome. diff --git a/docs/en/grunt.md b/docs/en/contributing-to-appium/grunt.md similarity index 97% rename from docs/en/grunt.md rename to docs/en/contributing-to-appium/grunt.md index 1effcb8d4..bb3899a4b 100644 --- a/docs/en/grunt.md +++ b/docs/en/contributing-to-appium/grunt.md @@ -1,4 +1,4 @@ -# Appium grunt commands +## Appium grunt commands [Grunt](http://gruntjs.com) is like make for Node.js! We use it to automate all kinds of appium dev tasks. Here's what you can do: @@ -22,7 +22,7 @@ kinds of appium dev tasks. Here's what you can do: |grunt generateAppiumIo|Take Appium's README.md and turn it into HTML for getting-started.html of appium.io| |grunt setConfigVer:<device>|Say that <device> is configured for the version of Appium listed in package.json| -## Miscellaneous notes +### Miscellaneous notes By default, `grunt buildApp` builds apps using the iPhone 7.1 simulator SDK. You can overwrite the simulator by passing another SDK to grunt (to figure out diff --git a/docs/en/how-to-write-docs.md b/docs/en/contributing-to-appium/how-to-write-docs.md similarity index 55% rename from docs/en/how-to-write-docs.md rename to docs/en/contributing-to-appium/how-to-write-docs.md index 5a5894fe2..00156408f 100644 --- a/docs/en/how-to-write-docs.md +++ b/docs/en/contributing-to-appium/how-to-write-docs.md @@ -1,17 +1,17 @@ -# How to write docs +## How to write docs -`#` is used to write a h1 header. Each document must start with a h1 header. -Don't use the `===` underline method of creating headers. +`##` is used to write a h2 header. Each document must start with a h2 header. +This is to support appium.io docs genration.Don't use the `---` underline method of creating headers. +Don't use h1 `#` or `===` for heading as it is not supported for table of contents (folder name is used as h1). -## Subheaders +### Subheaders -`##` is used to write subheaders. Don't use the `---` underline method of -creating sub headers. +`###` is used to write subheaders. ### Regular headers -`###` is used for headers that don't appear in the table of contents. -Don't use h4 `####`, h5 `#####`, or h6 `######`. +`####` is used for headers that don't appear in the table of contents. +Don't use h5 `#####`, or h6 `######`. ### Line breaks diff --git a/docs/en/style-guide.md b/docs/en/contributing-to-appium/style-guide.md similarity index 97% rename from docs/en/style-guide.md rename to docs/en/contributing-to-appium/style-guide.md index 36ea3564c..c003a964e 100644 --- a/docs/en/style-guide.md +++ b/docs/en/contributing-to-appium/style-guide.md @@ -1,18 +1,18 @@ -# Style guide for contributors +## Style guide for contributors Thanks for your contribution to Appium! Here are the principles we use when writing javascript. Please conform to these so we can merge your pull request without going back and forth about style. The main principle is: *make your code look like the surrounding code*. -## Rebasing +### Rebasing Commits in a pull request should consist of [logical changes](https://github.com/appium/appium/pull/920#issuecomment-21588553). If there are multiple authors, make sure each author has their own commit. It's not a good idea to modify author information. Merge commits should be rebased out of pull requests. -## Linting +### Linting All code (except for code in `bootstrap.js` which uses proprietary Apple methods) must pass JSLint. To check your code, you can simply run `grunt @@ -65,7 +65,7 @@ editor. See [this page for jshint](http://www.jshint.com/platforms/) and get the list of editors and platforms supported and how setup your editor for automatic linting. -## Style notes +### Style notes * Use two spaces for indentation, *no tabs* * Use single spaces around operators @@ -76,8 +76,8 @@ automatic linting. not ```javascript var x=1; - ``` - + ``` + * Spaces after commas and colons in lists, objects, function calls, etc... ```javascript @@ -183,7 +183,7 @@ automatic linting. }; // Create a subclass - + var SubClass = function () { this.init(); }; @@ -208,7 +208,7 @@ automatic linting. ```javascript function myFunc (a, b, c) {} ``` - + * Variable names should be camelCased: ```javascript @@ -229,8 +229,8 @@ automatic linting. myVariable === undefined ``` -## Test Style: - +### Test Style: + Keep on the same line if it makes sense semantically and length is not an issue: Examples: @@ -238,7 +238,7 @@ Examples: ```javascript driver.elementByTagName('el1').should.become("123") .nodeify(done); - + driver .elementsByTagName('el1').should.eventually.have.length(0) .nodeify(done); diff --git a/docs/en/appium-bindings.md b/docs/en/writing-running-appium/appium-bindings.md similarity index 96% rename from docs/en/appium-bindings.md rename to docs/en/writing-running-appium/appium-bindings.md index 4a4aea5e6..baad5daff 100644 --- a/docs/en/appium-bindings.md +++ b/docs/en/writing-running-appium/appium-bindings.md @@ -1,4 +1,4 @@ -# Appium Client Libraries +## Appium Client Libraries Appium has libraries for: @@ -23,7 +23,7 @@ not generally useful. Proper coverage support will be added once [this issue](ht is resolved. `complexFind()` will be removed once [this issue](https://github.com/appium/appium/issues/2264) is resolved. If you want to use them anyway, consult the documentation for the bindings on GitHub. -## Lock +### Lock Lock the screen. @@ -57,7 +57,7 @@ $this->lock(3); driver.LockDevice(3); ``` -## Background app +### Background app Send the currently active app to the background. @@ -91,7 +91,7 @@ $this->backgroundApp(5); driver.BackgroundApp(5); ``` -## Hide Keyboard +### Hide Keyboard Hide the keyboard. @@ -126,7 +126,7 @@ $this->hideKeyboard(array('strategy' => 'pressKey', 'key' => 'Done')); driver.HideKeyboard("Done"); ``` -## Is installed +### Is installed Check if an app is installed @@ -161,7 +161,7 @@ $this->isAppInstalled('com.example.android.apis'); driver.IsAppInstalled("com.example.android.apis-"); ``` -## Install App +### Install App Install an app to the device. @@ -195,7 +195,7 @@ $this->installApp('path/to/my.apk'); driver.InstallApp("path/to/my.apk"); ``` -## Remove App +### Remove App Remove an app from the device. @@ -229,7 +229,7 @@ $this->removeApp('com.example.android.apis'); driver.RemoveApp("com.example.android.apis"); ``` -## Shake +### Shake Simulate the device shaking. @@ -263,7 +263,7 @@ $this->shake(); driver.ShakeDevice(); ``` -## Close app +### Close app Close the app @@ -297,7 +297,7 @@ $this->closeApp(); driver.CloseApp(); ``` -## Launch +### Launch Launch the app @@ -331,7 +331,7 @@ $this->launchApp(); driver.LaunchApp(); ``` -## Reset +### Reset Reset the app. @@ -365,7 +365,7 @@ $this->reset(); driver.ResetApp(); ``` -## Available Contexts +### Available Contexts List all available contexts @@ -399,7 +399,7 @@ $this->contexts(); driver.GetContexts() ``` -## Current context +### Current context List the current context @@ -434,7 +434,7 @@ $this->context(); driver.GetContext() ``` -## Switch to default context +### Switch to default context Change the context to the default. @@ -468,7 +468,7 @@ $this->context(NULL); driver.SetContext(); ``` -## App Strings +### App Strings Get the app's strings. @@ -503,7 +503,7 @@ $this->appStrings('ru'); driver.GetAppStrings(); ``` -## Key Event +### Key Event Send a key event to the device. @@ -537,7 +537,7 @@ $this->keyEvent('176'); driver.KeyEvent("176"); ``` -## Current Activity +### Current Activity Android only. Get the current activity. @@ -571,7 +571,7 @@ $this->currentActivity(); driver.GetCurrentActivity(); ``` -## TouchAction / MultiTouchAction +### TouchAction / MultiTouchAction An API for generating touch actions. This section of the documentation will be expanded upon soon. @@ -640,7 +640,7 @@ action.Press(el, 10, 10).Release(); action.Perform (); ``` -## Swipe +### Swipe Simulate a user swipe. @@ -686,7 +686,7 @@ $this->swipe(75, 500, 75, 0, 800); todo: c# ``` -## Pinch +### Pinch Pinch the screen. @@ -746,7 +746,7 @@ $this->pinch($el); driver.Pinch(25, 25) ``` -## Zoom +### Zoom Zoom the screen. @@ -807,7 +807,7 @@ $this->zoom($el); driver.Zoom(100, 200); ``` -## Scroll To +### Scroll To Scroll to an element. @@ -848,7 +848,7 @@ $this->scroll($els[count($els) - 1], $els[0]); todo: csharp ``` -## Pull file +### Pull file Pulls a file from the device. @@ -883,7 +883,7 @@ $this->pullFile('Library/AddressBook/AddressBook.sqlitedb'); driver.PullFile("Library/AddressBook/AddressBook.sqlitedb"); ``` -## Push File +### Push File Pushes a file to the device. @@ -925,7 +925,7 @@ $this->pushFile($path, base64_encode($data)); driver.PushFile("/data/local/tmp/file.txt", "some data for the file"); ``` -## Appium Desktop Apps +### Appium Desktop Apps Appium's desktop app supports OS X and Windows. diff --git a/docs/en/caps.md b/docs/en/writing-running-appium/caps.md similarity index 99% rename from docs/en/caps.md rename to docs/en/writing-running-appium/caps.md index b79401cec..30fb80bf3 100644 --- a/docs/en/caps.md +++ b/docs/en/writing-running-appium/caps.md @@ -1,4 +1,4 @@ -# Appium server capabilities +## Appium server capabilities diff --git a/docs/en/finding-elements.md b/docs/en/writing-running-appium/finding-elements.md similarity index 95% rename from docs/en/finding-elements.md rename to docs/en/writing-running-appium/finding-elements.md index 343807678..4701c33bc 100644 --- a/docs/en/finding-elements.md +++ b/docs/en/writing-running-appium/finding-elements.md @@ -1,4 +1,4 @@ -# Finding and interacting with elements +## Finding and interacting with elements Appium supports a subset of the WebDriver locator strategies: @@ -15,12 +15,12 @@ search using the UiAutomator Api (Android-only) * `accessibility id`: a string corresponding to a recursive element search using the Id/Name that the native Accessibility options utilize. -## Issues +### Issues There's a known issue with table cell elements becoming invalidated before there's time to interact with them. We're working on a fix -## Using The Appium Inspector To Locate Elements +### Using The Appium Inspector To Locate Elements Appium provides you with a neat tool that allows you to find the the elements you're looking for without leaving the Appium app. With the Appium Inspector diff --git a/docs/en/ios_predicate.md b/docs/en/writing-running-appium/ios_predicate.md similarity index 97% rename from docs/en/ios_predicate.md rename to docs/en/writing-running-appium/ios_predicate.md index 0ab2a96c8..35bfb41d9 100644 --- a/docs/en/ios_predicate.md +++ b/docs/en/writing-running-appium/ios_predicate.md @@ -1,4 +1,4 @@ -# iOS Predicate +## iOS Predicate It is worth looking at *'-ios uiautomation'* search strategy with **Predicates**. [UIAutomation JavaScript API](https://developer.apple.com/library/ios/documentation/DeveloperTools/Reference/UIAutomationRef/_index.html) has following methods which can are very useful. @@ -22,7 +22,7 @@ appiumDriver.findElementsByIosUIAutomation("collectionViews()[0].cells().withPre Here's a list of available Predicates (mostly taken from [Predicates Programming Guide](https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/Predicates/predicates.html)) -## Basic Comparisons +### Basic Comparisons = , == - The left-hand expression is equal to the right-hand expression: @@ -58,7 +58,7 @@ NSPredicate *betweenPredicate = This creates a predicate that matches ```( ( 1 <= attributeValue ) && ( attributeValue <= 10 ) )``` -## Boolean Value Predicates +### Boolean Value Predicates TRUEPREDICATE - A predicate that always evaluates to ```TRUE``` . @@ -66,7 +66,7 @@ TRUEPREDICATE FALSEPREDICATE - A predicate that always evaluates to ```FALSE```. -## Basic Compound Predicates +### Basic Compound Predicates AND , && - Logical AND. @@ -77,7 +77,7 @@ OR , || NOT , ! - Logical NOT. -## String Comparisons +### String Comparisons String comparisons are by default case and diacritic sensitive. You can modify an operator using the key characters ```c``` and ```d``` within square braces to specify case and diacritic insensitivity respectively, for example ```firstName BEGINSWITH[cd] $FIRST_NAME``` @@ -120,7 +120,7 @@ tableViews().firstWithPredicate("value MATCHES '.*of 7' ") same in Xpath: /UIATableView[matches(@value, '.*of 7')][1] ``` -## Aggregate Operations +### Aggregate Operations ANY , SOME - Specifies any of the elements in the following expression. For example ```ANY children.age < 18``` . @@ -156,7 +156,7 @@ elements()[0].tableViews()[0].cells().withPredicate("staticTexts[SIZE] > 2") same in Xpath: /*[1]/UIATableView[1]/UIATableCell[count(UIAStaticText) > 2] ``` -## Identifiers +### Identifiers **C style identifier** - Any C style identifier that is not a reserved word. @@ -173,7 +173,7 @@ same in Xpath: /*[1]/UIATableView[1]/UIATableCell[count(UIAStaticText) > 2] **[\\][uU]{hexdigit}{4}** - Used to escape a Unicode number ( ```\u``` or ```\U``` followed by 4 hex digits). -## Literals +### Literals Single and double quotes produce the same result, but they do not terminate each other. For example, ```"abc"``` and ```'abc'``` are identical, whereas ```"a'b'c"``` is equivalent to a space-separated concatenation of ```a, 'b', c```. @@ -213,13 +213,13 @@ SELF 0b - Prefix used to denote a binary digit sequence. -## Reserved Words +### Reserved Words The following words are reserved: `AND, OR, IN, NOT, ALL, ANY, SOME, NONE, LIKE, CASEINSENSITIVE, CI, MATCHES, CONTAINS, BEGINSWITH, ENDSWITH, BETWEEN, NULL, NIL, SELF, TRUE, YES, FALSE, NO, FIRST, LAST, SIZE, ANYKEY, SUBQUERY, CAST, TRUEPREDICATE, FALSEPREDICATE` -## Appium predicate helpers +### Appium predicate helpers Appium has [helpers for predicate search](https://github.com/appium/appium-uiauto/blob/3052dace828db2ab3d722281fb7853cbcbc3252f/uiauto/appium/app.js#L68) in app.js: diff --git a/docs/en/mobile-web.md b/docs/en/writing-running-appium/mobile-web.md similarity index 97% rename from docs/en/mobile-web.md rename to docs/en/writing-running-appium/mobile-web.md index c9cfed5ce..8036f8faa 100644 --- a/docs/en/mobile-web.md +++ b/docs/en/writing-running-appium/mobile-web.md @@ -1,11 +1,11 @@ -# Automating mobile web apps +## Automating mobile web apps If you're interested in automating your web app in Mobile Safari on iOS or Chrome on Android, Appium can help you. Basically, you write a normal WebDriver test, and use Appium as the Selenium server with a special set of desired capabilities. -## Mobile Safari on Simulator +### Mobile Safari on Simulator First of all, make sure developer mode is turned on in your Safari preferences so that the remote debugger port is open. @@ -58,7 +58,7 @@ capabilities.setCapability("browserName", "Safari"); capabilities.setCapability("deviceName", "iPhone Simulator"); ``` -## Mobile Safari on a Real iOS Device +### Mobile Safari on a Real iOS Device To be able to run your tests against mobile Safari we use the [SafariLauncher App](https://github.com/snevesbarros/SafariLauncher) to launch Safari. Once @@ -70,7 +70,7 @@ in the ios-webkit-debug-proxy. You have to trust the machine before you can run the ios-webkit-debug-proxy against your iOS device. -## Setup +### Setup Before you can run your tests against Safari on a real device you will need to: * Have the **ios-webkit-debug-proxy** installed, running and listening on port 27753 (see the @@ -106,11 +106,11 @@ $ ./reset.sh --ios --real-safari --code-sign '' --profile $ node /lib/server/main.js -U ``` -## Running your test +### Running your test To configure you test to run against safari simply set the **"browserName"** to be **"Safari"**. -## Java Example +### Java Example ```java // java @@ -130,7 +130,7 @@ remoteWebDriver.findElement(By.id("comments")).sendKeys("My comment"); //populat remoteWebDriver.quit(); ``` -## Python Example +### Python Example ```python # python @@ -178,7 +178,7 @@ class ContextTests extends PHPUnit_Extensions_AppiumTestCase } ``` -## Mobile Chrome on Emulator or Real Device +### Mobile Chrome on Emulator or Real Device Pre-requisites: diff --git a/docs/en/network_connection.md b/docs/en/writing-running-appium/network_connection.md similarity index 96% rename from docs/en/network_connection.md rename to docs/en/writing-running-appium/network_connection.md index f5dcff905..3b7444a01 100644 --- a/docs/en/network_connection.md +++ b/docs/en/writing-running-appium/network_connection.md @@ -1,4 +1,4 @@ -# Adjusting Network Connection +## Adjusting Network Connection The Selenium [Mobile JSON Wire Protocol Specification](https://code.google.com/p/selenium/source/browse/spec-draft.md?repo=mobile) supports an [API](https://code.google.com/p/selenium/source/browse/spec-draft.md?repo=mobile#104) for getting and setting the network connection for a device. The API works through a bitmask, assigning an integer to each possible state: @@ -10,12 +10,12 @@ The Selenium [Mobile JSON Wire Protocol Specification](https://code.google.com/p | 4 (Data only) | 1 | 0 | 0 | | 6 (All network on) | 1 | 1 | 0 | -## iOS +### iOS Unfortunately, at the moment Appium does not support the Selenium network connection API for iOS. -## Android +### Android Choose the setting you would like to use, and then send the correct bitmask from the table above. diff --git a/docs/en/running-tests.md b/docs/en/writing-running-appium/running-tests.md similarity index 96% rename from docs/en/running-tests.md rename to docs/en/writing-running-appium/running-tests.md index f986de2c4..78f5f7f80 100644 --- a/docs/en/running-tests.md +++ b/docs/en/writing-running-appium/running-tests.md @@ -1,6 +1,6 @@ -# Running Tests +## Running Tests -## Preparing your app for test (iOS) +### Preparing your app for test (iOS) Test apps run on the simulator have to be compiled specifically for the simulator, for example by executing the following command in the Xcode project: @@ -14,12 +14,12 @@ Appium server. If you want, you can zip up the .app directory into a .zip file! Appium will unpack it for you. Nice if you're not using Appium locally. -## Preparing your app for test (Android) +### Preparing your app for test (Android) Nothing in particular needs to be done to run your .apk using Appium. If you want to zip it up, you can. -## Running your test app with Appium (iOS) +### Running your test app with Appium (iOS) The best way to see what to do currently is to look at the example tests: @@ -85,7 +85,7 @@ capabilities and connect to the server running at port 4723 of localhost (or whatever host and port you specified when you started Appium). You should be all set now! -## Running your test app with Appium (Android) +### Running your test app with Appium (Android) 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 @@ -165,7 +165,7 @@ capabilities and connect to the server running at port 4723 of localhost (or whatever host and port you specified when you started Appium). You should be all set now! -## Running your test app with Appium (Android devices < 4.2, and hybrid tests) +### Running your test app with Appium (Android devices < 4.2, and hybrid tests) Android devices before version 4.2 (API Level 17) do not have Google's [UiAutomator framework](http://developer.android.com/tools/help/uiautomator/index.html) diff --git a/docs/en/server-args.md b/docs/en/writing-running-appium/server-args.md similarity index 99% rename from docs/en/server-args.md rename to docs/en/writing-running-appium/server-args.md index fafd4f55c..2340c09fc 100644 --- a/docs/en/server-args.md +++ b/docs/en/writing-running-appium/server-args.md @@ -1,8 +1,8 @@ -# Appium server arguments +## Appium server arguments Usage: `node . [flags]` -## Server flags +### Server flags All flags are optional, but some are required in conjunction with certain others. diff --git a/docs/en/touch-actions.md b/docs/en/writing-running-appium/touch-actions.md similarity index 96% rename from docs/en/touch-actions.md rename to docs/en/writing-running-appium/touch-actions.md index f2aafd19a..2a490dd92 100644 --- a/docs/en/touch-actions.md +++ b/docs/en/writing-running-appium/touch-actions.md @@ -1,4 +1,4 @@ -# Automating mobile gestures +## Automating mobile gestures While the Selenium WebDriver spec has support for certain kinds of mobile interaction, its parameters are not always easily mappable to the functionality @@ -13,9 +13,9 @@ These APIs allow you to build up arbitrary gestures with multiple actuators. Please see the Appium client docs for your language in order to find examples of using this API. -## An Overview of the TouchAction / MultiAction API +### An Overview of the TouchAction / MultiAction API -## TouchAction +### TouchAction *TouchAction* objects contain a chain of events. @@ -64,7 +64,7 @@ TouchAction().tap(el).perform() driver.perform(TouchAction().tap(el)) ``` -## MultiTouch +### MultiTouch *MultiTouch* objects are collections of TouchActions. @@ -87,7 +87,7 @@ MultiAction().add(action0).add(action1).perform() -## Bugs and Workarounds +### Bugs and Workarounds An unfortunate bug exists in the iOS 7.x Simulator where ScrollViews don't recognize gestures initiated by UIAutomation (which Appium uses under the hood diff --git a/docs/en/uiautomator_uiselector.md b/docs/en/writing-running-appium/uiautomator_uiselector.md similarity index 98% rename from docs/en/uiautomator_uiselector.md rename to docs/en/writing-running-appium/uiautomator_uiselector.md index eb98f701b..483184767 100644 --- a/docs/en/uiautomator_uiselector.md +++ b/docs/en/writing-running-appium/uiautomator_uiselector.md @@ -1,4 +1,4 @@ -# uiautomator UiSelector +## uiautomator UiSelector Appium enables searching using [UiSelectors](http://developer.android.com/tools/help/uiautomator/UiSelector.html). [UiScrollable](http://developer.android.com/tools/help/uiautomator/UiScrollable.html) diff --git a/docs/en/unicode.md b/docs/en/writing-running-appium/unicode.md similarity index 98% rename from docs/en/unicode.md rename to docs/en/writing-running-appium/unicode.md index 47e1be91f..74d9848f3 100644 --- a/docs/en/unicode.md +++ b/docs/en/writing-running-appium/unicode.md @@ -1,9 +1,9 @@ -# Multi-lingual Support +## Multi-lingual Support By default the automation tools for both iOS and Android do not support non-ASCII characters sent to editable fields through the keyboard. -## iOS +### iOS Appium sends non-ASCII characters to iOS editable fields directly, bypassing the keyboard altogether. While this allows the text to be inputted in tests, it should @@ -36,7 +36,7 @@ driver .nodeify(done); ``` -## Android +### Android Android tests allow for Unicode input by installing and using a [specialized keyboard](https://github.com/appium/io.appium.android.ime) that allows the text