Appium Java client has facilities which components to [Page Object](https://github.com/SeleniumHQ/selenium/wiki/PageObjects) design pattern and [Selenium PageFactory](https://github.com/SeleniumHQ/selenium/wiki/PageFactory). # WebElement/list of WebElement field can be populated by default: ```java import org.openqa.selenium.WebElement; import org.openqa.selenium.support.FindBy; ... @FindBy(someStrategy) //for browser or web view html UI //also for mobile native applications when other locator strategies are not defined WebElement someElement; @FindBy(someStrategy) //for browser or web view html UI //also for mobile native applications when other locator strategies are not defined List<WebElement> someElements; ``` # If there is need to use convinient locators for mobile native applications then the following is available: ```java import io.appium.java_client.android.AndroidElement; import org.openqa.selenium.remote.RemoteWebElement; import io.appium.java_client.pagefactory.*; import io.appium.java_client.ios.IOSElement; @AndroidFindBy(someStrategy) //for Android UI when Android UI automator is used AndroidElement someElement; @AndroidFindBy(someStrategy) //for Android UI when Android UI automator is used List<AndroidElement> someElements; @SelendroidFindBy(someStrategy) //for Android UI when Selendroid automation is used RemoteWebElement someElement; @SelendroidFindBy(someStrategy) //for Android UI when Selendroid automation is used List<RemoteWebElement> someElements; @iOSFindBy(someStrategy) //for iOS native UI IOSElement someElement; @iOSFindBy(someStrategy) //for iOS native UI List<IOSElement> someElements; ``` # The example for the crossplatform mobile native testing ```java import io.appium.java_client.MobileElement; import io.appium.java_client.pagefactory.*; @AndroidFindBy(someStrategy) @iOSFindBy(someStrategy) MobileElement someElement; @AndroidFindBy(someStrategy) //for the crossplatform mobile native @iOSFindBy(someStrategy) //testing List<MobileElement> someElements; ``` # The fully cross platform example ```java import org.openqa.selenium.remote.RemoteWebElement; import io.appium.java_client.pagefactory.*; import org.openqa.selenium.support.FindBy; //the fully cross platform example @FindBy(someStrategy) //for browser or web view html UI @AndroidFindBy(someStrategy) //for Android native UI @iOSFindBy(someStrategy) //for iOS native UI RemoteWebElement someElement; //the fully cross platform example @FindBy(someStrategy) @AndroidFindBy(someStrategy) //for Android native UI @iOSFindBy(someStrategy) //for iOS native UI List<RemoteWebElement> someElements; ``` # Also it is possible to define chained or any possible locators. ## - Chained ```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; @FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) RemoteWebElement someElement; @FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) List<RemoteWebElement> someElements; ``` or ```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; import static io.appium.java_client.pagefactory.LocatorGroupStrategy.CHAIN; @HowToUseLocators(androidAutomation = CHAIN, iOSAutomation = CHAIN) @FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) RemoteWebElement someElement; @HowToUseLocators(androidAutomation = CHAIN, iOSAutomation = CHAIN) @FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) List<RemoteWebElement> someElements; ``` ## - Any possible ```java import org.openqa.selenium.remote.RemoteWebElement; import io.appium.java_client.pagefactory.*; import org.openqa.selenium.support.FindBy; import org.openqa.selenium.support.FindByAll; import static io.appium.java_client.pagefactory.LocatorGroupStrategy.ALL_POSSIBLE; @HowToUseLocators(androidAutomation = ALL_POSSIBLE, iOSAutomation = ALL_POSSIBLE) @FindAll{@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) RemoteWebElement someElement; @HowToUseLocators(androidAutomation = ALL_POSSIBLE, iOSAutomation = ALL_POSSIBLE) @FindAll({@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) List<RemoteWebElement> someElements; ``` ## Also possible combined variants for target platforms: ```java import org.openqa.selenium.remote.RemoteWebElement; import io.appium.java_client.pagefactory.*; import org.openqa.selenium.support.FindBy; import org.openqa.selenium.support.FindByAll; import static io.appium.java_client.pagefactory.LocatorGroupStrategy.CHAIN; import static io.appium.java_client.pagefactory.LocatorGroupStrategy.ALL_POSSIBLE; @HowToUseLocators(androidAutomation = CHAIN, iOSAutomation = ALL_POSSIBLE) @FindAll{@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) RemoteWebElement someElement; @HowToUseLocators(androidAutomation = CHAIN, iOSAutomation = ALL_POSSIBLE) @FindAll({@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) List<RemoteWebElement> someElements; ``` or ```java import org.openqa.selenium.remote.RemoteWebElement; import io.appium.java_client.pagefactory.*; import org.openqa.selenium.support.FindBy; import org.openqa.selenium.support.FindByAll; import static io.appium.java_client.pagefactory.LocatorGroupStrategy.ALL_POSSIBLE; @HowToUseLocators(iOSAutomation = ALL_POSSIBLE) @FindAll{@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) //this is the chain //by default @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) RemoteWebElement someElement; @HowToUseLocators(iOSAutomation = ALL_POSSIBLE) @FindAll({@FindBy(someStrategy1), @FindBy(someStrategy2)}) @AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) //this is the chain //by default @iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) 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: - ```java import io.appium.java_client.pagefactory.*; import org.openqa.selenium.support.PageFactory; PageFactory.initElements(new AppiumFieldDecorator(searchContext /*searchContext is a WebDriver or WebElement instance */), pageObject //an instance of PageObject.class ); ``` - ```java import io.appium.java_client.pagefactory.*; import org.openqa.selenium.support.PageFactory; import java.util.concurrent.TimeUnit; PageFactory.initElements(new AppiumFieldDecorator(searchContext, /*searchContext is a WebDriver or WebElement instance */ 15, //default implicit waiting timeout for all strategies TimeUnit.SECONDS), pageObject //an instance of PageObject.class ); ``` - ```java import io.appium.java_client.pagefactory.*; import org.openqa.selenium.support.PageFactory; import java.util.concurrent.TimeUnit; PageFactory.initElements(new AppiumFieldDecorator(searchContext, /*searchContext is a WebDriver or WebElement instance */ new TimeOutDuration(15, //default implicit waiting timeout for all strategies TimeUnit.SECONDS)), pageObject //an instance of PageObject.class ); ``` If time of the waiting for elements differs from usual (longer, or shorter when element is needed only for quick checkings/assertions) then ```java import io.appium.java_client.pagefactory.*; import java.time.temporal.ChronoUnit; @WithTimeout(timeOut = yourTime, chronoUnit = yourTimeUnit) RemoteWebElement someElement; @WithTimeout(timeOut = yourTime, chronoUnit = yourTimeUnit) List<RemoteWebElement> someElements; ``` # The additional feature. ## The simple example Let's imagine that the task is to check an Android client of the [http://www.rottentomatoes.com](http://www.rottentomatoes.com/). Let it be like a picture below  Lets imagine that it is only a part of the screen. A typical page object could look like: ```java public class RottenTomatoesScreen { //convinient locator private List<AndroidElement> titles; //convinient locator private List<AndroidElement> scores; //convinient locator private List<AndroidElement> castings; //element declaration goes on public String getMovieCount(){ //....... } public String getTitle(params){ //....... } public String getScore(params){ //....... } public String getCasting(params){ //....... } public void openMovieInfo(params){ //....... } //method declaration goes on } ``` The description above can be decomposed. Let's work it out! Firstly a Movie-widget could be described this way: ```java import io.appium.java_client.pagefactory.Widget; import org.openqa.selenium.WebElement; public class Movie extends Widget{ protected Movie(WebElement element) { super(element); } //convinient locator private AndroidElement title; //convinient locator private AndroidElement score; //convinient locator private AndroidElement casting; public String getTitle(params){ //....... } public String getScore(params){ //....... } public String getCasting(params){ //....... } public void openMovieInfo(params){ ((AndroidElement) getWrappedElement()).tap(1, 1500); } } ``` So, now page object looks ```java public class RottenTomatoesScreen { @AndroidFindBy(a locator which convinient to find a single movie-root - element) private List<Movie> movies; //element declaration goes on public String getMovieCount(){ return movies.size(); } public Movie getMovie(int index){ //any interaction with sub-elements of a movie-element //will be performed outside of the page-object instance return movie.get(index); } //method declaration goes on } ``` ### Ok. What if Movie-class is reused and a wrapped root element is usually found by the same locator? Then ```java //the class is annotated !!! @AndroidFindBy(a locator which convinient to find a single movie-root - element) public class Movie extends Widget{ ... } ``` and ```java public class RottenTomatoesScreen { //!!! locator is not necessary at this case private List<Movie> movies; ... } ``` ### Ok. What if movie list is not a whole screen? E.g. we want to describe it as a widget with nested movies. Then: ```java //with the usual locator or without it public class Movies extends Widget{ //with a custom locator or without it private List<Movie> movies; ... } ``` and ```java public class RottenTomatoesScreen { //with a custom locator or without it Movies movies; ... } ``` ### Good! How to poputate all these fields? As usual: ```java RottenTomatoesScreen screen = new RottenTomatoesScreen(); PageFactory.initElements(new AppiumFieldDecorator(searchContext /*WebDriver or WebElement instance */), screen); ``` ## Specification A class which describes a widget or group of elements should extend ```java io.appium.java_client.pagefactory.Widget; ``` Any widget/group of elements can be described it terms of sub-elements or nested sub-widgets. Appium-specific annotations are used for this purpose. ### Any class which describes the real widget or group of elements can be annotated That means that when the same "widget" is used frequently and any root element of this can be found by the same locator then user can ```java @FindBy(relevant locator) //how to find a root element public class UsersWidget extends Widget{ @FindBy(relevant locator) //this element will be found //using the root element WebElement subElement1; @FindBy(relevant locator) //this element will be found //using the root element WebElement subElement2; @FindBy(relevant locator) //a root element //of this widget is the sub-element which //will be found from top-element UsersWidget subWidget; //and so on.. } ``` and then it is enough ```java //above is the other field declaration UsersWidget widget; //below is the other field/method declaration ``` If the widget really should be found using an another locator then ```java //above is the other field declaration @FindBy(another relevant locator) //this locator overrides //the declared in the using class UsersWidget widget; //below is the other field/method declaration ``` ### Ok. What should users do if they want to implement a subclass which describes a similar group of elements for the same platform? There is nothing special. ```java @FindBy(relevant locator) //how to find a root element public class UsersWidget extends Widget{ ... } ``` ```java //at this case the root element will be found by the locator //which is declared in superclass public class UsersOverriddenWidget extends UsersWidget { ... } ``` and ```java @FindBy(relevant locator2) //this locator overrides //all locators declared in superclasses public class UsersOverriddenWidget2 extends UsersWidget { ... } ``` ### Is it possible to reuse "widgets" in crossplatform testing? If there is no special details of interaction with an application browser version and/or versions for different mobile OS's then ```java @FindBy(relevant locator for browser/webview html or by default) @AndroidFindBy(relevant locator for Android UI automator) @iOSFindBy(relevant locator for iOS UI automation) public class UsersWidget extends Widget { @FindBy(relevant locator for browser/webview html or by default) @AndroidFindBy(relevant locator for Android UI automator) @iOSFindBy(relevant locator for iOS UI automation) RemoteWebElement subElement1; @FindBy(relevant locator for browser/webview html or by default) @AndroidFindBy(relevant locator for Android UI automator) @iOSFindBy(relevant locator for iOS UI automation) RemoteWebElement subElement2; //overrides a html/default //locator declared in the used class @FindBy(relevant locator for browser/webview html or by default) //overrides an Android UI automator //locator declared in the used class @AndroidFindBy(relevant locator for Android UI automator) //overrides an iOS UI automation //locator declared in the using class @iOSFindBy(relevant locator for iOS UI automation) UsersWidget subWidget; //and so on.. } ``` ### What if interaction with a "widget" has special details for each used platform, but the same at high-level Then it is possible ```java public /*abstract*/ class DefaultAbstractUsersWidget extends Widget{ } ``` and ```java @FindBy(locator) public class UsersWidgetForHtml extends DefaultAbstractUsersWidget { } ``` and ```java @AndroidFindBy(locator) public class UsersWidgetForAndroid extends DefaultAbstractUsersWidget { } ``` and even ```java @iOSFindBy(locator) public class UsersWidgetForIOS extends DefaultAbstractUsersWidget { } ``` and then ```java import io.appium.java_client.pagefactory.OverrideWidget; ... //above is the other field declaration @OverrideWidget(html = UsersWidgetForHtml.class, androidUIAutomator = UsersWidgetForAndroid.class, iOSUIAutomation = UsersWidgetForIOS .class) DefaultAbstractUsersWidget widget; //below is the other field/method declaration ``` This use case has some restrictions; - All classes which are declared by the OverrideWidget annotation should be subclasses of the class declared by field - All classes which are declared by the OverrideWidget should not be abstract. If a declared class is overriden partially like ```java //above is the other field declaration @OverrideWidget(iOSUIAutomation = UsersWidgetForIOS .class) DefaultUsersWidget widget; //lets assume that there are differences of //interaction with iOS and by default we use DefaultUsersWidget. //Then DefaultUsersWidget should not be abstract too. // //below is the other field/method declaration ``` - for now it is not possible to ```java import io.appium.java_client.pagefactory.OverrideWidget; ... //above is the other field declaration @OverrideWidget(html = UsersWidgetForHtml.class, androidUIAutomator = UsersWidgetForAndroid.class, iOSUIAutomation = UsersWidgetForIOS .class) DefaultAbstractUsersWidget widget; //below is the other field/method declaration //user's code ((UsersWidgetForAndroid) widget).doSpecialWorkForAndroing() ``` The workaround: ```java import io.appium.java_client.pagefactory.OverrideWidget; ... //above is the other field declaration @OverrideWidget(html = UsersWidgetForHtml.class, androidUIAutomator = UsersWidgetForAndroid.class, iOSUIAutomation = UsersWidgetForIOS .class) DefaultAbstractUsersWidget widget; //below is the other field/method declaration //user's code ((UsersWidgetForAndroid) widget.getSelfReference()).doSpecialWorkForAndroing() ``` ### Good! What about widget lists? All that has been mentioned above is true for "widget" lists. ### One more restriction It is strongly recommended to implement each subclass of __io.appium.java_client.pagefactory.Widget__ with this constructor ```java public /*or any other available modifier*/ WidgetSubclass(WebElement element) { super(element); } ```