appium():PageObject&PageFactory

Appium Java client has facilities which components to Page Object design pattern and Selenium PageFactory.//appium的java客戶端支持PageObject和PageFactory。讀本文之前一定要有PageObject和PageFactory的概念。

原文地址：https://github.com/appium/java-client/blob/master/docs/Page-objects.md#specification

 

//第一部分：講解聲明filed時，如何使用注解

WebElement/list of WebElement field can be populated by default:

//對於WebElement使用@Findby注解，元素類型是WebElement。

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:

//對於移動端原生應用，分別使用@AndroidFindBy@SelendroidFindBy@iOSFindBy注解，元素類型分別為AndroidElement、RemoteWebElement、IOSElement。

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

//跨平台時，同時使用@AndroidFindBy@iOSFindBy注解，元素類型為MobileElement。

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 examle

//全平台時，同時使用@FindBy@AndroidFindBy@iOSFindBy注解，元素類型為RemoteWebElement。

import org.openqa.selenium.remote.RemoteWebElement;
import io.appium.java_client.pagefactory.*;
import org.openqa.selenium.support.FindBy;

//the fully cross platform examle
@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 examle
@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是指使用@FindBys、@AndroidFindBys、@iOSFindBys注解。修飾列表變量時，列表的內容是多個定位方法找到的元素。修飾非列表變量時，變量值是什么呢？

- Chained

If you use build versions < 5.x.x

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)}) 
@AndroidFindBys({@AndroidFindBy(someStrategy1), @AndroidFindBy(someStrategy2)}) 
@iOSFindBys({@iOSFindBy(someStrategy1), @iOSFindBy(someStrategy2)}) 
RemoteWebElement someElement;

@FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
@AndroidFindBys({@AndroidFindBy(someStrategy1), @AndroidFindBy(someStrategy2)}) 
@iOSFindBys({@iOSFindBy(someStrategy1), @iOSFindBy(someStrategy2)}) 
List<RemoteWebElement> someElements;

If you use build versions >= 5.x.x

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

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;

//possible是指使用@FindAll@AndroidFindAll@iOSFindAll注解。如果修飾列表變量，那么列表的內容是由全部聲明的定位方法找到的元素。如果修飾非列表變量，那么變量值是第一個被找到的元素，無論是使用哪個已聲明的定位方法。

- Any possible

If you use build versions < 5.x.x

import org.openqa.selenium.remote.RemoteWebElement;
import io.appium.java_client.pagefactory.*;
import org.openqa.selenium.support.FindBy;
import org.openqa.selenium.support.FindByAll;

@FindAll({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
@AndroidFindAll({@AndroidFindBy(someStrategy1), @AndroidFindBy(someStrategy2)}) 
@iOSFindAll({@iOSFindBy(someStrategy1), @iOSFindBy(someStrategy2)}) 
RemoteWebElement someElement;

@FindAll({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
@AndroidFindAll({@AndroidFindBy(someStrategy1), @AndroidFindBy(someStrategy2)}) 
@iOSFindAll({@iOSFindBy(someStrategy1), @iOSFindBy(someStrategy2)}) 
List<RemoteWebElement> someElements;

If you use build versions >= 5.x.x

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:

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

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;

 

 

//第二部分：講解如何使用PageFactory初始化field。

Appium Java client is integrated with Selenium PageFactory by AppiumFieldDecorator.

Object fields are populated as below://按照這個方式初始化。

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
);

 

 //初始化時，可以設置元素定位的超時時間。

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//效果為：至少用15個時間單位查找元素。
        TimeUnit.SECONDS), 
            pageObject //an instance of PageObject.class
);
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)), //效果為：至少用15個時間單位查找元素。

pageObject //an instance of PageObject.class 22 );

If time of the waiting for elements differs from usual (longer, or shorter when element is needed only for quick checkings/assertions) then//還可以為每個元素單獨設置超時時間。

import io.appium.java_client.pagefactory.*;

@WithTimeout(timeOut = yourTime, timeUnit = yourTimeUnit)
RemoteWebElement someElement;

@WithTimeout(timeOut = yourTime, timeUnit = 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. 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://典型的page object的寫法

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!//上面的PageObject寫法，可以進行拆解。

Firstly a Movie-widget could be described this way://首先，定義一個widget：猜測是頁面上的一個對象，假設爛番茄網站上也有電視劇、動畫片的信息，而這兩者又有不同的介紹，比如電視劇有演員信息，動畫片有配音人員和設計師的信息，那么電視劇和動畫可以看做是兩個不同的widget。

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  //大多時候，不同movie的具有相同的id或者classname，這時候用id或者classname就可以定位全部的movie。同理，不同movie的title也都有相同的id或者classname，一個定位字符串可以通用與全部的title。
   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

public class RottenTomatoesScreen {

     @AndroidFindBy(a locator which convinient to find a single movie-root - element)//不同movie具有相同的id或者classname，這時候一個定位字符串可以通用於全部的movie。  4      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//如果需要使用movie類生成多個實例，而且這些實例使用同一個定位字符串，那么可以將實例的注解移到定義movie類的代碼前面。

//the class is annotated !!!
@AndroidFindBy(a locator which convinient to find a single movie-root - element)
public class Movie extends Widget{
...
}

 

and

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://這里是說，如何生成一個特殊的widget，它的內部元素還是widget。假設當前頁面是一個內容非常豐富的頁面，有電影、電視劇、綜藝節目相關的信息，電影分類內部的每個電影都有名字、得分、劇情簡介等信息，電視劇和綜藝節目也有各自的內部信息。此時，每部電影都是一個小的widget，電影類別則是一個大的widget，整個頁面由電影、電視劇、綜藝節目三個大的widget組成。注解的使用方法同前面一樣。

//with the usual locator or without it
public class Movies extends Widget{

    //with a custom locator or without it
    private List<Movie> movies;
...
}

 

and

public class RottenTomatoesScreen {

    //with a custom locator or without it
    Movies movies;
...
}

 

Good! How to poputate all these fields?

As usual:

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//要想使用widget，必須要繼承widget類。

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

@FindBy(relevant locator) //how to find a root element//假設UsersWidget對應於實際頁面的movie，那么這個定位字符串是能夠匹配全部movie的通用的字符串。
public class UsersWidget extends Widget{

  @FindBy(relevant locator) //this element will be found //同理，這里的定位字符串也必須是通用的匹配全部subElement1的字符串。
  //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

  //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

  //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.//子類繼承父類沒有特殊的操作。

@FindBy(relevant locator) //how to find a root element
public class UsersWidget extends Widget{
... 
}
//at this case the root element will be found by the locator
//which is declared in superclass
public class UsersOverriddenWidget extends UsersWidget {
... 
}

 

and

@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

@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

public /*abstract*/ class DefaultAbstractUsersWidget extends Widget{

}

 

and

@FindBy(locator)
public class UsersWidgetForHtml extends DefaultAbstractUsersWidget {

}

 

and

@AndroidFindBy(locator)
public class UsersWidgetForAndroid extends DefaultAbstractUsersWidget {

}

 

and even

@iOSFindBy(locator)
public class UsersWidgetForIOS extends DefaultAbstractUsersWidget {

}

 

and then

  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

  //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

  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:

  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

   public /*or any other available modifier*/ WidgetSubclass(WebElement element) {
       super(element);
   }