#page objects

[qualitytesting]

XCTest and the Page Object Model

What's a Page Object?

The page object model is the generally accepted pattern to use when writing automated tests. The gist of it is that in order to create a maintainable test suite, you will reduce duplication in your code by creating an object for each page in your product, and storing all the information and logic around locating elements, performing actions etc. inside the respective page object. Your test code will then interact with the app through these objects.

The page object model has traditionally been applied primarily to websites, but with the introduction of mobile applications, the page object model is now being translated for use with frameworks like Appium and Calabash, which provide an interface with which to test mobile apps. When applied to mobile apps, it is sometimes referred to as the screen object model, due to the difference in terminology between websites and mobile apps.

How do I use Page Objects with XCTest?

XCTest is a framework created by Apple, which doesn't adhere to the WebDriver protocol. This means that the way you use it is a bit different. If you're familiar with Selenium WebDriver, or a relation of it (Appium's interface is an extension of WebDriver's), it can be a bit intimidating to have to learn a new structure.

Here's my translation of how to use page objects with XCTest:

Architecture Overview

My test classes all inherit from XCTestCase. Test classes are named descriptively to quickly communicate the starting state of the tests they contain.

Each test class constructs a reference to a startPage object during setUp(), which is used as the initial state for all tests in that class. setUp() methods may handle the dismissal of any onboarding UI, and will determine that the state of the app is correct e.g. a setUp() method from a descendant of the SignedInTests class will ensure that the user is signed in.

Each test class also holds a reference to a UITestHelper object. This object contains convenience APIs which handle actions involving multiple pages, as it is not appropriate for a page object to contain a method which functions across different pages.

Page objects have been made to represent each page that the tests interact with. These objects encapsulate the implementation details of each page in the app, and are a huge part of conforming to the Don't Repeat Yourself (DRY) principle. Each page object holds a reference to the currently-running test case, where it will be able to access any stored contextual information.

Page objects are used by the tests and the UITestHelper. The page objects expose behavioural APIs to enable the author of the UI tests to write interactions in the same way that a user would think about interacting with what's on their screen.

The TabBarPage object and its descendants implement methods associated with interacting with the UITabBar in the app - which only appears on some pages. While the TabBarPage displays an API of available interactions and knows the logic required for those interactions, it is the TabBarInteractor which houses the implementation details - like a page object for the tab bar, except it's not a page object because its qualities are not unique to a page. The methods available on TabBarPage and its descendants will delegate actions to the TabBarInteractor in order to interact with the UITabBar.

Page Object Structure

Every page object inherits from Page. Page only contains properties and methods that are applicable to every page.

import XCTest class Page: NSObject { // Properties for other pages to inherit let app = XCUIApplication() let testCase: UITestCase class var awaitTimeout: Double class var uniqueElement: XCUIElement class var exists: Bool // Initializer for other pages to inherit init(testCase: UITestCase) // Called on initialization. Waits for the unique element to exist before continuing. // Initialization fails if the unique element is not found within `awaitTimeout` seconds. func await(file: String = #file, line: UInt = #line) }

All page objects will be able to:

Use app to interact with the application and discover the state of elements.

Access testCase to retrieve contextual information about the currently-running test.

Wait for up to awaitTimeout seconds for themselves to load - this will be a higher number for pages which are expected to load more slowly.

Work out whether the page they're representing exists on-screen by searching for the presence of a uniqueElement, which is unique to that page.

The awaitTimeout, uniqueElement and exists properties are variables to allow them to be overridden by descendants, and are class (static) variables because they don't need to be tied to an instance of a page to be calculated. For example, I can find out whether a page exists or not without having to initialize it. If I had to initialize the page, I would have to wait for the awaitTimeout to pass before finding out that the page does not exist, and I would then have to prevent the test from failing

On initialization, the active test case class will be injected and stored, and the page will await itself. This means that the page object will wait for its counterpart in the app to appear on-screen. After a certain amount of time has passed (defined by awaitTimeout), if the page's uniqueElement is still not found, the await method will fail the test using XCTFail().

Awaiting each page on initialization creates a "checkpoint" of sorts - every time the test facilitates a page change, a check is run to ensure that that page really does exist. This enables the test to fail faster if something's not as it expects, and prevents the initialization and attempted use of pages which aren't on-screen.

import XCTest class ProductListPage: TabPage { // Internally accessible properties override class var uniqueElement: XCUIElement override var tabBarScrollableView: XCUIElement? var isEmpty: Bool // Private properties private var productCollection: XCUIElement private var noResultsLabel: XCUIElement private var cells: XCUIElementQuery // Internally accessible methods func goToProductDetailPageForProductAtIndex(index: UInt) -> ProductDetailPage func goToProductDetailPageForProductWithName(name: String) -> ProductDetailPage func goToProductDetailPageForUnsavedItem(offset: Int = 0) -> ProductDetailPage func goToProductDetailPageForSavedItem(offset: Int = 0) -> ProductDetailPage func addItemToSaved(offset: Int = 0) -> String func getIndexForCell(saved: Bool, offset: Int) -> UInt func isSavedForProductWithName(name: String) -> Bool // Private methods private func scrollUpProductList() private func goToProductDetailPage(saved: Bool = false, offset: Int = 0) -> ProductDetailPage private func getCellForProductWithName(name: String) -> XCUIElement private func getCellAtIndex(index: UInt) -> XCUIElement private func getSavedButtonForCell(cell: XCUIElement) -> XCUIElement private func getTitleForCell(cell: XCUIElement) -> String }

The first thing to note here is the application of a page object model principle: Page object methods which change the page (or screen) that the user is viewing will initialize and return a page object representing the new page. This allows test authors to see where, if anywhere, a method will take them.

This rule of having to return a page object from navigational methods is one of the places where using a type-safe language like Swift comes in really handy (instead of a dynamic language like Ruby or Python) - your code won't compile if you're not returning the right type of page. This is not only great for catching programming errors early, but it's also a very powerful way of driving the design of your code; it prevents you from writing overly-configurable methods and forces you to create separation between different paths through the app. Combined with the await part of your page object initialization, this ensures that different paths through the app are represented discretely. This is a cleaner way of designing your classes, and also means that your method names can be more specific about what they do.

Each page descending from Page should override the uniqueElement property to ensure that the class can identify whether or not it exists. For pages with a UITabBar which may disappear from view when the user scrolls through a list, tabBarScrollableView may be overridden to specify a scrollable view which can be interacted with to bring the tab bar back onto the screen.

Not all properties should be public. In general, all properties and methods returning XCUIElement or XCUIElementQuery objects should be private, to prevent any other objects from interacting with them. Page objects should only interact with their corresponding page, and no other objects should be able to interact directly with the app.

The methods which are internally accessible (no need for these to be public, as these classes won't be used by a third party) all represent either actions that the user could perform on this page, or information from the page that the user would be able to see. Information may take the form of a get... method or a Boolean calculation.

The private methods are those which are only useful to this page. No other objects should be interested in using them - they are assistants to the internally accessible methods, but they have no place being used by other objects.

Test Structure

The tests themselves are structured in pretty much the same way as any test that uses page objects.

import XCTest class SignedInTests: UITestCase { /** Performs test setup for all signed in tests. - Signs in if the user is signed out on launch. - Returns to the home page for the test to begin. */ override func setUp() { super.setUp() // Sign in if !isSignedIn { let meUnauthenticatedPage = startPage.goToMeTabExpectingRootUnauthenticatedPage() let signInPage = meUnauthenticatedPage.goToSignInPage() let meAuthenticatedPage = signInPage.signInAsValidUserExpectingMePage(user!) startPage = meAuthenticatedPage.goToHomeTabExpectingRootPage() } } // Performs test tear down. override func tearDown() { super.tearDown() } /** Given I am signed in When I sign out Then I will be signed out */ func testSignOut() { // Sign out let meAuthenticatedPage = startPage.goToMeTabExpectingRootAuthenticatedPage() meAuthenticatedPage.signOut() // Check you are signed out XCTAssertTrue(MeUnauthenticatedPage.exists) } }

The test class is called SignedInTests so the setUp() function ensures that you are signed in before the test begins, making sure that startPage is set to the home page again before it finishes. It also calls super.setUp() before anything else - ensuring that all of the setup actions it inherited are done too.

The test begins by navigating away from startPage. It brings up the MeAuthenticatedPage (in the app I'm testing, the "Me" page (which shows information about me) is completely different depending on whether you're signed in or not, so they are separate page objects.) and signs out. The signOut() method returns a MeUnauthenticatedPage object, but as I'm not going to do anything with that page, there's no point in storing it. The last part of the test is the assertion - in this case, checking that the page I expect to be on-screen does exist.

Under the hood, there's a lot of lines of code going into making this test work, but thanks to my architecture, most of those lines are obscured. The test code becomes very readable and easy to follow, and the test suite as a whole is easy to maintain, as the implementation logic is encapsulated in page objects.

[simplythetest]

Devil in the Details: Page Object Edition

// <![CDATA[ function styleCode() { if (typeof disableStyleCode != 'undefined') { return; } var a = false; $('code').each(function() { if (!$(this).hasClass('prettyprint')) { $(this).addClass('prettyprint'); a = true; } }); if (a) { prettyPrint(); } } $(function() {styleCode();}); // ]]>

One thing that all test developers can agree on is that the Page Object (PO) design pattern has been a great benefit to test development. I endorse this view, since I love page objects myself. As a Selenium developer, I can't think of a better way to organize application logic for tests.

Clearly, developers should make use of this pattern. Just create a base page class, add a constructor call that checks the pages title and throws an error if the found title is not correct, and then start building specific pages from there, right?

I'm sure about half the test devs reading that last part nodded along without any concern. The other half just threw up in their mouths a little bit.

This is what I've noticed about the PO design: everyone thinks the PO pattern is great, but no one agrees on the actual implementation details.

For example, let's take return types. One popular convention in for POs is that POs return POs. It's a simple premise that has a host of benefits like method chaining and easy method synchronization among others. An example would be as follows: class WidgetsPage extends BasePage {

    // using the "POs return POs" approach     public WidgetsPage createWidget(){

        // details

        return this;

    }

    public SprocketsPage editSprocket() {

        // details

        return new SprocketsPage();     } } Contrast this to the view endorsed by others to not return POs and return nothing instead: class WidgetsPage extends BasePage {

    // not returning POs     public void createWidget(){

        // details

        return;     }

    public void editSprocket() {

        // details  

        return;     } } At first glance, this may not seem like a dramatic difference. Once you start to work with such POs, which form your POs take can greatly affect what you can do with your test code. For example, code like int getSprocketNumberFromWidget(){     return new WidgetPage()         .createWidget()         .editSprocket()         .getSprocketNumber() } can't be written as such without methods that return POs. It must be re-worked to look like int getSprocketNumberFromWidget(){     widgetPage = new WidgetPage()     widgetPage.createWidget()     sprocketPage = widgetPage.editSprocket()     return sprocketPage.getSprocketNumber() }

And then there's other patterns, such as having methods return boolean values or something similar. This approach looks even more different from the above.

Which you prefer may depend on readability and language, or just plain coding style preference (even though the former approach produces a bunch of great beneficial side effects). The problem can be when those styles are mixed and matched, since one does not necessarily play well with the other. When some POs return POs and others don't, strange test code can appear. This goes double for languages like Java with explicit typing.

Another controversial topic is error handling within POs. Should POs throw errors, or not? You could construct methods like this: int getSprocketNumber(){     if (listOfSprockets == 0){         assert.fail("No Sprockets Found");     }

    // continue with getting the value } or you could construct methods like this: int getSprocketNumber() {     if (listOfSprockets == 0){         // no sprockets found, return a value indicating such         return -1;     }

   // continue with getting the value } Some test developers like putting asserts in POs under the theory that failures should be detected as soon as possible and that some functionality should "always" work. In my opinion putting asserts into POs breaks the separation between test logic and application logic, making POs harder to build upon. One of the more interesting aspects of the PO pattern is that you can reuse POs not just in additional tests but elsewhere as well. Still, both patterns are in active use by test developers.

I'm sure there's other variants of the PO pattern out there. Just thinking about how languages like Java and Python differ themselves is reason enough to consider different approaches. What I've found more important than choosing the "correct" way of using POs is being consistent about your methods. Certain patterns that work great alone work much less effectively together. And vice versa.

Overall I don't think this is a bad thing at all. After all, test development is still testing. What works in one setting may not work in another. It's not like there's a standard, One True Way when it comes to POs. It's also a relatively new idea on the software development block, so it's still evolving. Good ideas should appear and displace bad ones over time.

[simplythetest]

Page Objects are Great, Part 3

In continuing my series on Page Objects, I want to discuss the second property of POs from my first post, namely that

Page Objects contain at least some class methods that return other Page Object (possibly of the same class), meaning there closure between Page Objects

This property is a bit obvious and a bit subtle. The idea is that POs truly represent the web app they model, without any obvious leaks (even if all abstractions are kind of bad), and that you don't have to introduce any modelling hocus pocus to make them work.

How does this property accomplish this? Let's see some examples.

Suppose your app has two pages, a home page and a contact page. Each page has a link to the other page that is always present (you can always directly click from one to the other). Using POs, you can model this relation in the following way (with code reuse from previous posts): 

public class HomePage extends BasePage {

    public HomePage(driver) {

        superclass(driver);

    }

    public ContactPage goToContactPage() {

        // navigate to contact page

        return new ContactPage(driver);

}

public class ContactPage extends BasePage {

    public ContactPage(driver) {

        superclass(driver);

    }

    public HomePage goToHomePage() {

        // navigate to home page

        return new HomePage(driver);

}

Now, with these definitions in place, here's part of a test script that includes navigating between the two pages: 

HomePage home = new HomePage(driver);

// ...

// go from the home page to the contact page

ContactPage contact = home.goToContactPage()

// do interesting stuff, then go back to the home page

home = contact.goToHomePage()

Great! You can now clearly see the relationships between your pages and how your tests trace through them. It resembles (at least partially) how a driver "walks" through pages of web app. 

There are more benefits though. Notice that the each PO's constructor is called every time a goToPage()-type method is called. This means that any checks or conditions that the constructor contains get done each time such a method is called. It's almost like "free" checking, in the sense that you don't have to manually place these checks at the end of any given method. That's a bit of a win when you start to look at the PO design pattern in practice, with many methods called and scripts run.

And of course, these points apply to methods that do more than directly link from one page to another. You could argue that any user action "navigates" from a page to a "new" page, even if that page is an identical copy of the same page, so this concept is applicable to wide range of actions that take place on a given page.

It's also clear that the driver member of a given script (or PO) is cleanly handled. No more mucking about keeping track of static drivers or objects that need messy initialization methods called periodically during tests. 

As well, another main benefit of this property is that the capabilities of each page are clearly described while the actual implementation details are hidden. For example, in the goToHomePage() method, you could go to the home page by clicking a link or by redirecting using a URL. The actual details are irrelevant, as long as you end up on the expected page. Put differently, your test scripts are independent of the script/driver details, which is key. This applies doubly to less obvious methods such clicking a button that takes the user to a new page, or a scenario where an invalid action leads to a different page.

There are some lesser benefits too, such method chaining. That means you can do things like 

phoneNumber =   home.goToContacts().getPhoneNumber();

This can be a good thing, but it can also be a problem when it comes to debugging. It may also make your code less readable more confusing. It's there anyway.

I am aware that there is some criticism of this property, and some advocate that POs do not necessarily have return other POs all the time or ever. I can see some possible downsides to my approach (garbage collection affecting performance is one) but I honestly think the way I've outlined is best, for now. You may also return the PO itself to preserve this approach (ie "return this" or "return self") to help avoid memory management problems. When implemented properly, it can clear up many common automated testing issues such as erroneous stale elements and waiting for loading pages. It can almost be magical. 

That's my description of Page Objects, hopefully with helpful examples. Let the testing begin. 

[simplythetest]

Page Objects are Great, Part 2

In my last post, I began a series discussing Page Objects (PO), and what makes them so great. This post will continue on the theme, talking about what makes Page Objects Page Objects.

Previously I gave two defining properties that, I think, are requirements for Page Objects. The first one was that a PO has:

A (private) driver object that is hidden away from public consumption, and is only handled via initialization/constructors

The key to this point is that the driver is a member of the PO class, and is mostly hidden from public PO calls. The driver should be only really be controlled at the highest levels of the PO hierarchy (i.e. in as few places as possible).  This also helps change the underlying driver type if required without a major rewrite since the driver definitions only have to be changed in a few specific places.

Here's a pseudo-code example of a very basic base class and how it contains a driver member: 

public class BasePage {

    protected _driver; 

    public BasePage(driver){

        this._driver = driver;  

    }

}

And that's it! It's the most basic case but all the important bits are there and completely valid. 

Let's see how an actual PO class representing a home page of a web site or app would be implemented: 

public class HomePage extends PageObject {

     public HomePage(driver) {

          superclass(driver)

     }

     // methods and fields that represent interactions with HomePage

}

And that's it! The driver member is completely encapsulated by the class. It can be accessed throughout the class, but not publicly by just any old object or function. 

Why is this great? Let's look at a couple of benefits. 

First, notice that I've just been using the term "driver" generically. In this post and the previous one I haven't mentioned Selenium (or Watir, or SilkTest, or some homegrown Franken-driver). This means that there's a clear level where the driver specifics are implemented. If you decide to change the particular browser driver, there's a clear place to do so and not some patchwork across classes and files. This isn't just a theoretical point: at work we are currently using Selenium and Silk4J, a Java binding of SilkTest that can drive browsers and desktop applications. It could happen that Selenium could be replaced with Silk4J (even if that would be widely regarded as a bad move). Yes the method details would have to be re-written, but at least Page Object structure stays the same, and you would almost certainly not have to re-write much of your test code, just the object/page side of things. 

Incidentally, I also haven't mentioned Java, Python, C++ or any other language. Page Objects illustrated here apply to any of those languages or others.

Second, using the PO pattern above simplifies writing method calls and signatures. Instead of having to pass a driver as an argument to all of HomePage's class methods, you have an internal driver instead. This means methods that might look like 

public bool isTitleCorrect(driver, expected_title)

now look like 

public bool isTitleCorrect(expected_title)

This saves a lot of typing, as it's a form of Don't Repeat Yourself. Code looks cleaner and is easier to understand, in my opinion. It also saves error checking and handling directly of a driver outside of a PO instance, which can be a big win. 

Lastly, and maybe most importantly, this pattern allows for checking right in the constructor! This is big; you can do some checking almost for free when you initialize new instances of pages (which will be discussed in Part 3).

Here's an example. One thing you want to do often is to confirm an action takes you to the correct page, like clicking a link. One way to do this is to check the page title is correct. Suppose that isTitleCorrect() is already a method of the PageObject class. Then we can add the appropriate call to the class constructor, something like this:

public BasePage(driver){

    this._driver = driver; 

    this._title = this.getPageTitle();

    if !(this.isTitleCorrect(this._title)) {

        Error("Incorrect Page Title"); 

        return;

}

Now, every PO automatically checks a page's title whenever a PO is initialized during tests. As we shall see in the next post, this is very helpful. It's almost like getting checks done for free, since every PO object now has this capability automatically. You can also add specific checks for different PO classes on top of the base PO checking as well. 

This post has gotten a bit long, so I'll stop here. I've outlined some benefits of how using a constructor/initialization approach to the Page Object pattern. If there's any downsides, I'd like to hear about them. 

In my next post, I will discuss the second point from my initial post in the series. 

[simplythetest]

Page Objects are Great, Part 1

Over the past weeks, I've reworked some test code I've been writing to implement the Page Object pattern.

And I've gotta say, it's great.

I'm totally getting into writing these tests. I know a lot of digital ink has been spilled writing about these objects. But I want to add my two cents and a bit about my experience with them over the next few posts. There's some technical bits coming, but maybe some personal experiences as well.

First off, let me mention the benefits of using the Page Object pattern. It provides a lightweight framework for writing tests in a reusable way. Done well, page objects provide a one-to-one correspondence between your web app and your test code. Because of this, test code is easier to write and maintain, as well as easier to read. Plus, all of this is language and platform independent. There's definitely a lot to love. 

As good as Page Objects have been, it's been an interesting journey for me, going from "Well, looks like I'm writing web GUI tests" to where I am today. I started out trying to write my tests using Page Objects correctly, then I got sidetracked, then I realized my tests weren't as good as I thought they could be, and finally I re-wrote them in a better way. I have a feeling I'm not the only tester/developer who's had a story like this, and I definitely won't be the last. 

There is plenty of good resources out there for learning about Page Objects, and some good examples of them out there. However, one thing I found is a lack of specifics out there. Examples are great, but what about exact situations I'm working with? There are a lot of in-depth discussions about login pages, but what about full-fledged enterprise web apps? How are message boxes handled? And so on. I also get the impression there's some confusion out there about how exactly Page Objects are implemented. 

As a contribution to this discussion, I'd like to give a more formal spec for what constitutes a Page Object. My definition would be this: a Page Object is an object representing a web (app) page with two properties: 

A (private) driver object that is hidden away from public consumption, and is only handled via initialization/constructors

Page Objects contain at least some class methods that return other Page Object (possibly of the same class), meaning there closure between Page Objects

If an object does not have both of these properties, I don't think it can properly be called a Page Object. It might be valid test code, maybe even good test code, but it's not a Page Object.

I'm going to discuss these aspects in more depth in future posts. When implemented correctly, these aspects provide some test functionality almost automatically. Like I said before, there's a lot to love about these things. 

Stay tuned for more posts in the series.

[iainrose]

Closing the (Page)Factory

Page Objects rock the party. No news there, they're awesome and most people using Selenium already know about them and have been using them for much longer than I have.

I learnt the basics about Page Objects from the Selenium Wiki. It's the best place to start and does a great job of explaining the concept but it's not perfect. 

The main complaint I have about this tutorial is that the locators are saved inline in the loginAs example method, this will quickly lead to duplication of locators within the Page Object and is not ideal.

driver.findElement(By.id("username")).sendKeys(username); driver.findElement(By.id("passwd")).sendKeys(password); driver.findElement(By.id("login")).submit();

It does however, link to the PageFactory wiki page which looked like a good idea to me so when I started my latest job sometime last year (my first new Selenium project since the Selenium 2 release) I quickly implemented the page factory along with my page objects ..... which turned out to be one of the two biggest mistakes I made early in the project which I'm still in the process of undoing.

@FindBy(id = "myElementId") WebElement myElement;

On first inspection it looks like a win, less boiler plate code == good, right? Well no, and here's why.

You cannot use WebElements created using the PageFactory to assert the absence of an element without wrapping a try catch block around them.

You cannot use WebElements created using the PageFactory to search within other WebElements.

You cannot use WebElements created using the PageFactory in all of the canned WebDriverWait ExpectedConditions (which also rock the party in a big way)

So what's the alternative?

By myElementLocator = By.id("myElementId")

Save your locators as By objects

This allows you to solve all the problems listed above and I've also noticed a reduction in the number of StaleElementExceptions I run into as I have a lot more control about when an element is looked up and assigned to a variable.

My example of how I think a sample page object should look can be found here.