Merge branch 'master' into readperformancedata

Author: heeseon

README.md

@@ -1,4 +1,4 @@
-#java-client
+# java-client
 
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.appium/java-client/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.appium/java-client)
 [![Javadoc](https://javadoc-emblem.rhcloud.com/doc/io.appium/java-client/badge.svg)](http://www.javadoc.io/doc/io.appium/java-client)
@@ -9,16 +9,73 @@ This is the Java language binding for writing Appium Tests, conforms to [Mobile
 
 [API docs](http://appium.github.io/java-client/)
 
-###Features and other interesting information###
+### Features and other interesting information
 
 [Tech stack](https://github.com/appium/java-client/blob/master/docs/Tech-stack.md)
 
 [How to install the project](https://github.com/appium/java-client/blob/master/docs/Installing-the-project.md)
 
 [WIKI](https://github.com/appium/java-client/wiki)
 
-##Changelog##
+## Changelog
+
 *5.0.0 (under construction yet)*
+- **[REFACTOR]** **[BREAKING CHANGE]** 5.0.0 finalization. Removal of obsolete code. [#660](https://github.com/appium/java-client/pull/660)
+- **[ENHANCEMENT]** Enable nativeWebTap setting for iOS. [#658](https://github.com/appium/java-client/pull/658)
+- **[ENHANCEMENT]** The `getCurrentPackage` was added. [#657](https://github.com/appium/java-client/pull/657)
+- **[ENHANCEMENT]** The `toggleTouchIDEnrollment` was added. [#659](https://github.com/appium/java-client/pull/659)
+- **[BUG FIX]** The clearing of existing actions/parameters after perform is invoked. [#663](https://github.com/appium/java-client/pull/663)
+
+*5.0.0-BETA9*
+- **[ENHANCEMENT]** Page factory: Mixed locator strategies were implemented. Feature request:[#565](https://github.com/appium/java-client/issues/565) Implementation: [#646](https://github.com/appium/java-client/pull/646)
+- **[DEPRECATED]** All the content of the `io.appium.java_client.youiengine` package was marked `Deprecated`. It is going to be removed. [#652](https://github.com/appium/java-client/pull/652)
+- **[UPDATE]** Update of the `com.google.code.gson:gson` to v2.8.1.
+
+*5.0.0-BETA8*
+- **[ENHANCEMENT]** Page factory classes became which had package visibility are `public` now. [#630](https://github.com/appium/java-client/pull/630)
+  - `io.appium.java_client.pagefactory.AppiumElementLocatorFactory`
+  - `io.appium.java_client.pagefactory.DefaultElementByBuilder`
+  - `io.appium.java_client.pagefactory.WidgetByBuilder`
+
+- **[ENHANCEMENT]** New capabilities were added [#626](https://github.com/appium/java-client/pull/626):
+  - `AndroidMobileCapabilityType#AUTO_GRANT_PERMISSIONS`
+  - `AndroidMobileCapabilityType#ANDROID_NATURAL_ORIENTATION`
+  - `IOSMobileCapabilityType#XCODE_ORG_ID`
+  - `IOSMobileCapabilityType#XCODE_SIGNING_ID`
+  - `IOSMobileCapabilityType#UPDATE_WDA_BUNDLEID`
+  - `IOSMobileCapabilityType#RESET_ON_SESSION_START_ONLY`
+  - `IOSMobileCapabilityType#COMMAND_TIMEOUTS`
+  - `IOSMobileCapabilityType#WDA_STARTUP_RETRIES`
+  - `IOSMobileCapabilityType#WDA_STARTUP_RETRY_INTERVAL`
+  - `IOSMobileCapabilityType#CONNECT_HARDWARE_KEYBOARD`
+  - `IOSMobileCapabilityType#MAX_TYPING_FREQUENCY`
+  - `IOSMobileCapabilityType#SIMPLE_ISVISIBLE_CHECK`
+  - `IOSMobileCapabilityType#USE_CARTHAGE_SSL`
+  - `IOSMobileCapabilityType#SHOULD_USE_SINGLETON_TESTMANAGER`
+  - `IOSMobileCapabilityType#START_IWDP`
+  - `IOSMobileCapabilityType#ALLOW_TOUCHID_ENROLL`
+  - `MobileCapabilityType#EVENT_TIMINGS`
+
+- **[UPDATE]** Dependencies were updated:
+  - `org.seleniumhq.selenium:selenium-java` was updated to 3.4.0
+  - `cglib:cglib` was updated to 3.2.5
+  - `org.apache.httpcomponents:httpclient` was updated to 4.5.3
+  - `commons-validator:commons-validator` was updated to 1.6
+  - `org.springframework:spring-context` was updated to 4.3.8.RELEASE
+
+
+*5.0.0-BETA7*
+- **[ENHANCEMENT]** The ability to customize the polling strategy of the waiting was provided. [#612](https://github.com/appium/java-client/pull/612) 
+- **[ENHANCEMENT]** **[REFACTOR]** Methods which were representing time deltas instead of elementary types became `Deprecated`. Methods which use `java.time.Duration` are suugested to be used. [#611](https://github.com/appium/java-client/pull/611)
+- **[ENHANCEMENT]** The ability to calculate screenshots overlap was included. [#595](https://github.com/appium/java-client/pull/595).
+
+
+*5.0.0-BETA6*
+- **[UPDATE]** Update to Selenium 3.3.1
+- **[ENHANCEMENT]** iOS XCUIT mode automation: API to run application in background was added. [#593](https://github.com/appium/java-client/pull/593)
+- **[BUG FIX]** Issue report: [#594](https://github.com/appium/java-client/issues/594). FIX: [#597](https://github.com/appium/java-client/pull/597)
+- **[ENHANCEMENT]** The class chain locator was added. [#599](https://github.com/appium/java-client/pull/599)
+
 
 *5.0.0-BETA5*
 - **[UPDATE]** Update to Selenium 3.2.0

archive/docs/How-to-propose-a-PR.md

@@ -1,4 +1,4 @@
-#A good pull-request should contain
+# A good pull-request should contain
 
 ### Change list
 
@@ -19,6 +19,6 @@ There should be provided more details about changes if it is necessary. If there
 can provide code samples which show the way they work and possible use cases. Also you can create [gists](https://gist.github.com) 
 with pasted java code samples or put them at a PR description using markdown. About markdown please read [Mastering markdown](https://guides.github.com/features/mastering-markdown/) and [Writing on GitHub](https://help.github.com/categories/writing-on-github/) 
 
-#Pull-request template
+# Pull-request template
 
 There is [PULL_REQUEST_TEMPLATE.md)](https://github.com/appium/java-client/blob/master/PULL_REQUEST_TEMPLATE.md) which should help you to make a good pull request.

archive/docs/How-to-report-an-issue.md

@@ -1,10 +1,10 @@
-#Be sure that it is not a server-side problem if you are facing something that looks like a bug
+# Be sure that it is not a server-side problem if you are facing something that looks like a bug
 
 The Appium Java client is the thin client which just sends requests and receives responces generally. 
 Be sure that this bug is not reported [here](https://github.com/appium/appium/issues) and/or there is
 no progress on this issue.
 
-#The good issue report should contain
+# The good issue report should contain
 
 ### Description
 
@@ -42,9 +42,9 @@ There should be created a [gist](https://gist.github.com) which is a paste of yo
 If you are reporting a bug, _always_ include Appium logs as linked gists! It helps to define the problem correctly and clearly. 
 
 
-#Issue template
+# Issue template
 There is [ISSUE_TEMPLATE.md](https://github.com/appium/java-client/blob/master/ISSUE_TEMPLATE.md) which should help you to make a good issue report.
 
-#... And don't say that you weren't warned. 
+# ... And don't say that you weren't warned. 
 
 If a report is not readable and/or there is no response from a reporter and some important details are needed then the issue will be closed after some time.

build.gradle

@@ -7,7 +7,7 @@ apply plugin: 'signing'
 apply plugin: 'maven-publish'
 
 group 'io.appium'
-version '5.0.0-BETA5'
+version '5.0.0-BETA9'
 
 repositories {
     jcenter()
@@ -54,20 +54,22 @@ compileJava {
 }
 
 dependencies {
-    compile('org.seleniumhq.selenium:selenium-java:3.2.0'){
+    compile('org.seleniumhq.selenium:selenium-java:3.4.0'){
         exclude module: 'cglib'
         exclude group: 'com.google.code.gson'
     }
-    compile 'com.google.code.gson:gson:2.8.0'
-    compile 'org.apache.httpcomponents:httpclient:4.5.2'
-    compile 'cglib:cglib:3.2.4'
-    compile 'commons-validator:commons-validator:1.5.1'
+    compile 'com.google.code.gson:gson:2.8.1'
+    compile 'org.apache.httpcomponents:httpclient:4.5.3'
+    compile 'cglib:cglib:3.2.5'
+    compile 'commons-validator:commons-validator:1.6'
     compile 'org.apache.commons:commons-lang3:3.5'
     compile 'commons-io:commons-io:2.5'
-    compile 'org.springframework:spring-context:4.3.5.RELEASE'
+    compile 'org.springframework:spring-context:4.3.8.RELEASE'
     compile 'org.aspectj:aspectjweaver:1.8.10'
+    compile 'org.openpnp:opencv:3.2.0-1'
 
     testCompile 'junit:junit:4.12'
+    testCompile 'org.hamcrest:hamcrest-all:1.3'
 }
 
 ext {

docs/Functions.md

@@ -1,6 +1,6 @@
 Appium java client has some features based on [Java 8 Functional interfaces](https://www.oreilly.com/learning/java-8-functional-interfaces).
 
-#Conditions
+# Conditions
 
 ```java
 io.appium.java_client.functions.AppiumFunction
@@ -58,7 +58,7 @@ private final AppiumFunction<Pattern, WebDriver> contextFunction = input -> {
 };
 ```
 
-##using one function as pre-condition
+## using one function as pre-condition
 
 ```java
 @Test public void tezt() {
@@ -70,7 +70,7 @@ private final AppiumFunction<Pattern, WebDriver> contextFunction = input -> {
 }
 ```
 
-##using one function as post-condition
+## using one function as post-condition
 
 ```java
 import org.openqa.selenium.support.ui.FluentWait;
@@ -85,7 +85,7 @@ import org.openqa.selenium.support.ui.Wait;
 }
 ```
 
-#Touch action supplier
+# Touch action supplier
 
 [About touch actions](https://github.com/appium/java-client/blob/master/docs/Touch-actions.md)
 
@@ -96,7 +96,7 @@ create gesture libraries/utils using suppliers. Appium java client provides this
 io.appium.java_client.functions.ActionSupplier
 ``` 
 
-##Samples
+## Samples
 
 ```java
 private final ActionSupplier<TouchAction> horizontalSwipe = () -> {

docs/How-to-propose-a-PR.md

@@ -1,4 +1,4 @@
-#A good pull-request should contain
+# A good pull-request should contain
 
 ### Change list
 
@@ -19,6 +19,6 @@ There should be provided more details about changes if it is necessary. If there
 can provide code samples which show the way they work and possible use cases. Also you can create [gists](https://gist.github.com) 
 with pasted java code samples or put them at a PR description using markdown. About markdown please read [Mastering markdown](https://guides.github.com/features/mastering-markdown/) and [Writing on GitHub](https://help.github.com/categories/writing-on-github/) 
 
-#Pull-request template
+# Pull-request template
 
 There is [PULL_REQUEST_TEMPLATE.md)](https://github.com/appium/java-client/blob/master/PULL_REQUEST_TEMPLATE.md) which should help you to make a good pull request.

docs/How-to-report-an-issue.md

@@ -1,10 +1,10 @@
-#Be sure that it is not a server-side problem if you are facing something that looks like a bug
+# Be sure that it is not a server-side problem if you are facing something that looks like a bug
 
 The Appium Java client is the thin client which just sends requests and receives responces generally. 
 Be sure that this bug is not reported [here](https://github.com/appium/appium/issues) and/or there is
 no progress on this issue.
 
-#The good issue report should contain
+# The good issue report should contain
 
 ### Description
 
@@ -42,9 +42,9 @@ There should be created a [gist](https://gist.github.com) which is a paste of yo
 If you are reporting a bug, _always_ include Appium logs as linked gists! It helps to define the problem correctly and clearly. 
 
 
-#Issue template
+# Issue template
 There is [ISSUE_TEMPLATE.md](https://github.com/appium/java-client/blob/master/ISSUE_TEMPLATE.md) which should help you to make a good issue report.
 
-#... And don't say that you weren't warned. 
+# ... And don't say that you weren't warned. 
 
 If a report is not readable and/or there is no response from a reporter and some important details are needed then the issue will be closed after some time.

docs/Installing-the-project.md

@@ -1,10 +1,10 @@
-#Requirements
+# Requirements
 
 Firstly you should install appium server. [Appium getting started](http://appium.io/getting-started.html). The version 1.6.3 or greater is recommended.
 
 Since version 5.x there many features based on Java 8. So we recommend to install JDK SE 8 and provide that source compatibility.
 
-#Maven
+# Maven
 
 Add the following to pom.xml:
 
@@ -40,7 +40,7 @@ If it is necessary to change the version of Selenium then you can configure pom.
 </dependency>
 ```
 
-#Gradle
+# Gradle
 
 Add the following to build.gradle:
 

docs/Page-objects.md

@@ -145,7 +145,7 @@ RemoteWebElement someElement;
 List<RemoteWebElement> someElements;
 ```
 
-## Also possible combined variants: 
+## Also possible combined variants for target platforms: 
 
 ```java
 import org.openqa.selenium.remote.RemoteWebElement;
@@ -194,6 +194,67 @@ RemoteWebElement someElement;
 List<RemoteWebElement> someElements;
 ``` 
 
+## Mixed chain/any locator strategy
+
+Some locator-element could not be defined certainly sometimes. It may be defined as one of possible variants/chained locator.
+If the using of _xpath_ is not convenient for some reasons so there are possible use cases
+
+### the chained searching 
+
+```java
+import org.openqa.selenium.remote.RemoteWebElement;
+import io.appium.java_client.pagefactory.*;
+import org.openqa.selenium.support.FindBys;
+import org.openqa.selenium.support.FindBy;
+
+//it is necessary to define priorities at this case. The lower number means the higher priority.
+//The default value is 0 (the highest priority)
+@iOSFindBy(someStrategy1)
+@iOSFindAll(value = {@iOSBy(subloctor1), @iOSBy(subloctor1)}, priority = 1) //it means that the chained searching contains
+//the searching by all possible locators as the element of the chain
+@iOSFindBy(someStrategy2, priority = 2) 
+@iOSFindBy(someStrategy3, priority = 3) 
+RemoteWebElement someElement;
+
+
+@iOSFindBy(someStrategy1)
+@iOSFindAll(value = {@iOSBy(subloctor1), @iOSBy(subloctor1)}, priority = 1) //it means that the chained searching contains
+//the searching by all possible locators as the element of the chain
+@iOSFindBy(someStrategy2, priority = 2) 
+@iOSFindBy(someStrategy3, priority = 3) 
+List<RemoteWebElement> someElements;
+```
+
+### all possible
+
+```java
+import org.openqa.selenium.remote.RemoteWebElement;
+import io.appium.java_client.pagefactory.*;
+import org.openqa.selenium.support.FindBys;
+import org.openqa.selenium.support.FindBy;
+
+//it is not necessary to define priorities at this case. But it can manage the searching.
+//The lower number means the higher priority.
+//The default value is 0 (the highest priority)
+@HowToUseLocators(iOSAutomation = ALL_POSSIBLE)
+@iOSFindBy(someStrategy1)
+@iOSFindBys(value = {@iOSBy(subloctor1), @iOSBy(subloctor1)}, priority = 1) //it means that the searching by all possible locators
+// contains the searching by chained locator as one of all possible variants
+@iOSFindBy(someStrategy2, priority = 2) 
+@iOSFindBy(someStrategy3, priority = 3) 
+RemoteWebElement someElement;
+
+
+
+@HowToUseLocators(iOSAutomation = ALL_POSSIBLE)
+@iOSFindBy(someStrategy1)
+@iOSFindBys(value = {@iOSBy(subloctor1), @iOSBy(subloctor1)}, priority = 1) //it means that the searching by all possible locators
+// contains the searching by chained locator as one of all possible variants
+@iOSFindBy(someStrategy2, priority = 2) 
+@iOSFindBy(someStrategy3, priority = 3) 
+List<RemoteWebElement> someElements;
+```
+
 # Appium Java client is integrated with Selenium PageFactory by AppiumFieldDecorator. 
 
 Object fields are populated as below: 

docs/Tech-stack.md

@@ -12,7 +12,7 @@ Also tech stack includes [Spring framework](https://projects.spring.io/spring-fr
 It is the client framework. It is the thin client which just sends requests to Appium server and receives responses. Also it has some
 high-level features which were designed to simplify user's work.
 
-#It supports: 
+# It supports: 
 
 ![](https://cloud.githubusercontent.com/assets/4927589/21467612/4b6b3f70-ca05-11e6-9a31-d3820e98dac6.png)  
 ![](https://cloud.githubusercontent.com/assets/4927589/21467614/73883828-ca05-11e6-846d-3ed8847a7e08.jpg)