dimanche 9 mars 2014

Page Object pattern with CasperJS

In this article I will quickly introduce an UI test framework, CasperJS, and how we can improve UI tests maintainability using the Page Object Pattern. The goal is not to cover all CasperJS features but to show how to write maintainable tests.

CasperJS is an open source tool used to test your web application user interface. From javascript code, you can simulate in a test all possible users interactions with your interface. For example you can click on a link, fill and submit a form, and finally check your DOM elements.

To start, let's see a concrete example of a CasperJS test and after we will see how to refactor the written tests using the Page Object pattern.

Our example

We will test three pages of the spring travel application :
  • the login page
  • the hotels search page & bookings listing
  • and the hotels search result page

Login page

Hotels search page & bookings listing


Hotels search result page

For our first CasperJS test, we want to cover the following scenario :
  • the user fills and submits the login form
  • the user arrives on the bookings listing
  • the user can see his last bookings
Here is the CasperJS test :

casper.test.begin('When I connect myself I should see my bookings', function (test) {
  casper.start(casper.cli.options.baseUrl + '/login');

  casper.then(function () {
    test.assertExists('form[name="f"]', 'Is on login page');
  });

  casper.then(function () {
    this.fill('form[name="f"]', {
      'j_username': 'scott',
      'j_password': 'rochester'
      }, false);
  });

  casper.then(function () {
    this.click('form[name="f"] button[type="submit"]', 'Login submit button clicked');
  });

  casper.then(function () {
    test.assertUrlMatch('hotels/search', 'Is on search page');
    test.assertTextExists('Current Hotel Bookings', 'bookings title are displayed');
    test.assertExists('#bookings > table > tbody > tr', 'bookings are displayed');
  });

  casper.run(function () {
    test.done();
  });
});

As you can see this test is very fluent and easily readable. Some explanations :
  • casper.start starts the scenario on a given url
  • casper.then sections describe a specific user action or some assertions.
  • fill and click methods allow to simulate user actions
  • assertExists, assertUrlMatch and assertTestExists allow to check the DOM content
  • casper.cli.options.baseUrl allows to get a custom parameter passed on the casper js command line
Now let's cover a little bit more complex scenario in a new CasperJS test :
  • the user fills and submits the login form
  • the user arrives on the hotels search page
  • the user fills and submits the hotels search page
  • the user can see several hotels in Atlanta

casper.test.begin('When I connect myself and search hotels in Atlanta 
Then should find three hotels', function (test) {
  casper.start(casper.cli.options.baseUrl + '/login');

  casper.then(function () {
    test.assertExists('form[name="f"]', 'Is on login page');
  });

  casper.then(function () {
    this.fill('form[name="f"]', {
      'j_username': 'scott',
      'j_password': 'rochester'
      }, false);
  });

  casper.then(function () {
    this.click('form[name="f"] button[type="submit"]', 'Login submit button clicked');
  });

  casper.then(function () {
    test.assertUrlMatch('hotels/search', 'Is on search page');
  });

  casper.then(function () {
    this.fill('form[id="searchCriteria"]', {
      'searchString': 'Atlanta'
      }, false);
  });

  casper.then(function () {
    this.click('form[id="searchCriteria"] button[type="submit"]');
  });

  casper.then(function () {
    test.assertUrlMatch('hotels?searchString=Atlanta', 'Is on search result page');
    test.assertElementCount('#hotelResults > table > tbody > tr', 3, '3 hotels have been found');
  });

  casper.run(function () {
    test.done();
  });
});


Again the test is fluent and readable. But a lot of code has just been copy/paste and we have now several duplicated lines of code.

How can we factorize that? By creating some utils methods? Not exactly, it is here that comes the famous Page Object pattern!

Page Object pattern

Page Object pattern is described on Martin Fowler website.

Page Object pattern by Martin Fowler


The main ideas are :

The test must not manipulate directly the page UI elements. This manipulation must be done within a Page Object which represents an UI page or an UI page fragment. The Page Object makes a complete abstraction of the underlying UI and it becomes an API where it is possible to easily find and manipulate the page data.

This encapsulation has two benefits : the test logic is about user intentions and not about UI details, so it is easier to understand. Plus, if the UI is modified, this will affect only the Page Objects and not the tests.

Asynchronism behavior of the pages must also be hidden by the Page Object. It is a specific behavior of your UI and you don't want to make it appear in your tests.

For a single page, you can have several Page Objects if there are several significant elements on the page. For example you can have a Page Object for the header and one for the body.

Assertions responsibility can be in the Page Object or in the test. In the Page Object it helps avoid duplication of assertions in the tests, but the Page Object responsibility becomes more complicated as it is responsible to give access to the page data, plus to have the assertion logic.

This pattern can be apply for any UI technologies : HTML pages, java swing interfaces or others UI.

Now, let's use the Page Object pattern for our CasperJS tests.

CasperJS with Page Object pattern

In our test, we navigate through three pages, so we will create three Page Objects : LoginPage, SearchPage and SearchResultPage.

Our first page is the login page. Here we must be able to start the scenario on this page, to check that the page is correct, and to fill and submit the login form. We will do that with four methods : startOnLoginPage, checkPage, fillForm and submitForm. All of these methods are created in a LoginPage object in a LoginPage.js file :

function LoginPage() {

  this.startOnLoginPage = function () {
    casper.echo("base url is : " + casper.cli.options.baseUrl);
    casper.start(casper.cli.options.baseUrl + '/login');
  };

  this.checkPage = function () {
    casper.then(function () {
      casper.test.assertUrlMatch('login', 'Is on login page');
      casper.test.assertExists('form[name="f"]', 'Login page form has been found');
    });
  };

  this.fillForm = function (username, password) {
    casper.then(function () {
      this.fill('form[name="f"]', {
        'j_username': username,
        'j_password': password
      }, false);
    });
  };

  this.submitForm = function () {
    casper.then(function () {
      this.click('form[name="f"] button[type="submit"]', 'Login submit button clicked');
    });
  };
}

Now we need a page for the search. We need to check the page, to check that the user bookings are displayed, and to fill and submit the search form. We will do that on a SearchPage object in the file SearchPage.js :

function SearchPage() {

  this.checkPage = function () {
    casper.then(function () {
      casper.test.assertUrlMatch('hotels/search', 'Is on search page');
    });
  };

  this.checkThatBookingsAreDisplayed = function() {
    casper.then(function () {
      casper.test.assertTextExists('Current Hotel Bookings', 'bookings title are displayed');
      casper.test.assertExists('#bookings > table > tbody > tr', 'bookings are displayed');
    });
  };

  this.fillSearchForm = function(searchTerms) {
    casper.then(function () {
      this.fill('form[id="searchCriteria"]', {
        'searchString': searchTerms
        }, false);
    });
  };

  this.submitSearchForm = function() {
    casper.then(function () {
      this.click('form[id="searchCriteria"] button[type="submit"]');
    });
  };
}

Finally we need a Page Object for our SearchResultPage. Here we just want to check the page and to check that the results are correctly displayed :

function SearchResultPage() {

  this.checkPage = function () {
    casper.then(function () {
      casper.test.assertUrlMatch('hotels?searchString=', 'Is on search result page');
    });
  };

  this.checkThatResultsAreDisplayed = function(expectedCount) {
    casper.then(function () {
      casper.test.assertElementCount('#hotelResults > table > tbody > tr', expectedCount, expectedCount + ' hotels have been found');
    });
  };
}

Now we can use these three Page Objects in our test :

phantom.page.injectJs('LoginPage.js');
phantom.page.injectJs('SearchPage.js');
phantom.page.injectJs('SearchResultPage.js');

var loginPage = new LoginPage();
var searchPage = new SearchPage();
var searchResultPage = new SearchResultPage();

casper.test.begin('When I connect myself I should see my bookings', function (test) {
  loginPage.startOnLoginPage();
  loginPage.checkPage();
  loginPage.fillForm('scott', 'rochester');
  loginPage.submitForm();

  searchPage.checkPage();
  searchPage.checkThatBookingsAreDisplayed();

  casper.run(function () {
    test.done();
  });
});

casper.test.begin('When I connect myself and search hotels in Atlanta 
Then should find three hotels', function (test) {
  loginPage.startOnLoginPage();
  loginPage.checkPage();
  loginPage.fillForm('scott', 'rochester');
  loginPage.submitForm();

  searchPage.checkPage();
  searchPage.fillSearchForm('Atlanta');
  searchPage.submitSearchForm();

  searchResultPage.checkPage();
  searchResultPage.checkThatResultsAreDisplayed(3);

  casper.run(function () {
    test.done();
  });
});

Our two tests are now more readable and there is a complete abstraction of UI elements. If you modify your HTML code, you will easily identify which page to modify and you won't have impacts on your tests.

Variant n°1 : use four Page Objects

The search page provides the search form and the bookings listing. I choose to modelize that in a single Page Object. But another option is to create two Page Object : one for the search and one for the listing. The BookingListingPage.js is now :

function BookingListingPage() {

  this.checkPage = function () {
    casper.then(function () {
      casper.test.assertUrlMatch('hotels/search', 'Is on booking listing page');
    });
  };

  this.checkThatBookingsAreDisplayed = function() {
    casper.then(function () {
      casper.test.assertTextExists('Current Hotel Bookings', 'bookings title are displayed');
      casper.test.assertExists('#bookings > table > tbody > tr', 'bookings are displayed');
    });
  };
}

And our first test becomes :

casper.test.begin('When I connect myself I should see my bookings', function (test) {
  loginPage.startOnLoginPage();
  loginPage.checkPage();
  loginPage.fillForm('scott', 'rochester');
  loginPage.submitForm();

  bookingListingPage.checkPage();
  bookingListingPage.checkThatBookingsAreDisplayed();

  casper.run(function () {
    test.done();
  });
});

Variant n°2 : keep assertions in tests

I choose to write the assertions directly in the Page Objects. Thess objects have then two responsibilities : give an access to the page data and provide assertions. Martin Fowler recommends to distinguish these responsitilibies and to keep assertions in the test. In that case the Page Object provides only an accessor to the page element and it is the test responsibility to check its content. For example for the SearchResultPage Object, the method :

// test
searchResultPage.checkThatResultsAreDisplayed(3);

// page object
this.checkThatResultsAreDisplayed = function(expectedCount) {
    casper.then(function () {
      casper.test.assertElementCount('#hotelResults > table > tbody > tr', expectedCount, expectedCount + ' hotels have been found');
    });
  };

Becomes :

// test
casper.test.assertEquals(searchResultPage.getResultsCount(), 3, '3 hotels have been found');

// page object
  this.getResultsCount = function() {
    return casper.evaluate(function() {
      return __utils__.findAll('#hotelResults > table > tbody > tr').length;
    });
  };


Conclusion

When you code your features, you don’t hesitate to separate the different layers in different objects. It is exactly what the Page Object pattern recommend to do : separate the test logic from the UI layer. In this article I applied it to CasperJS tests but this pattern is also relevant with other tools like for example Selenium, ZombieJS or even Gatling.

Please find the complete code on my github repository about tests.
Please also find my CasperJS best practices here.

8 commentaires:

  1. Hey that was a very nice introduction to the topic. I've been used to working with PO's in Selenium tests and they are a great way to distinct Tests from Business-Logic.

    After working with your example I found some things missing here. Maybe you could include how to work with distributed files where lets say the Tests are in test.js and the PO in po.js.

    my humble approach was something like this:

    po.js:
    // need to override global require as of PhantomJS implementation
    var require = patchRequire(require);

    // the page object is responsible to provide structured actions only
    // no test-assertions are made in here.
    // The benefit of this approach is that tests now can be written in a re-usable way
    // by simply grabbing the necessary pieces of the PO.
    var PO_General = function(casper) {
    var self = this;
    self.casper = casper;

    if(casper === undefined || casper === null) {
    throw "Casper instance not provided as constructor-argument for page object!";
    }

    self.myAction = function() {
    // Do your business logic
    self.casper.evaluate(function() {
    ...
    });
    };
    };

    exports.PageObject = PO_General;

    test.js:

    casper.test.begin('Execute Action from PO', 1, new function(){
    this.setUp = function() {
    // self-executing function to get the PageObject instance required + initialized at the same time
    this.PO_General = function() {
    var PageObjectDefintion = require('./PO_General').PageObject;
    return new PageObjectDefintion(casper);
    }();
    };

    this.test = function(test) {
    var self = this;

    casper.start('http://localhost:3000');

    casper.then(function() {
    // execute the Page Object Action
    self.PO_General.myAction();
    });

    casper.run(function(){
    test.done();
    })
    }

    });

    RépondreSupprimer
  2. Hi, I am getting a "ReferenceError: Can't find variable: LoginPage " when creating the var loginPage = new LoginPage();

    Looks like there is something missing!

    RépondreSupprimer
  3. Hey how would you apply variant two to filling data or clicking a button? And where could we look for more information on how to implement functionality with __util__. within casper?

    RépondreSupprimer
    Réponses
    1. Hi, more information on __util__ available here : http://docs.casperjs.org/en/latest/modules/clientutils.html

      Supprimer
    2. Variants 1 and 2 doesn't change the way you interact with a form but how you write your assertions. So you can refer to the main example for that :)

      Supprimer
  4. Your work is appreciable and you have amazing Blogging skills. I really recommended the readers to follow and share your idea in circles. I hope readers found it’s beneficial. Peoples should start blogging and try to forward information to others. Thanks and regards. Coupon and Discount Codes at LetCoupon

    RépondreSupprimer