Codeception 1.6.4: PageObjects and Friends

Another release that despite the minor version change brings major improvements. Meet 1.6.4, which adds lots of new ways to customize your test automation platform and improve your tests. And yes, before reading this post take a cup of coffee. We prepared lots of features for you and this long post.

PageObjects

Long awaited feature of adding PageObjects into the core. Codeception looks pretty different from other testing frameworks in Java or Ruby. So it was hard to understand in which way the PageObject should be implemented.

Actually you can think of a PageObject that is just a storage of UI locators (UI Map).

<?php
class ArticlesPage {

    const URL = '/articles';

    static $articleList = '#list';
    static $newArticleButton = '#toolbar a.new';

    static function row($id)
    {
        return $articleList ." .article-$id";
    }
}
?>

In a test you can use such PageObject this way:

<?php
$I = new WebGuy($scenario);
$I->wantTo('find article #1 in a list and edit it');
$I->amOnPage(ArticlesPage::URL);
$I->seeElement(ArticlesPage::$articleList);
$I->click('Edit', ArticlesPage::row(1));
$I->see('Editing Article #1');
?>

But how to make PageObjects actually to define page interaction too? Can we improve that? Sure! In a test they may look like:

<?php
$I = new WebGuy($scenario);
$I->wantTo('find article #1 in a list and edit it');
ArticlesPage::of($I)
    ->visit()
    ->openArticleForEditing(1);
$I->see('Editing Article #1');
?>

We have moved some logic into the PageObject class, and so we can reuse its methods in other tests. Read more on generating PageObjects on newly updated Guides page.

StepObject

Alternatively, interaction logic can be kept in StepObject classes. In which we recommend to define actions that may require passing through several pages. Also it may be useful if you want to define actions based on user roles.

<?php
$I = new WebGuy\AdminSteps($scenario);
$I->am('admin');
$I->wantTo('create a new admin and check his account');
$I->logIntoAdminArea();
$I->createUser('davert','123456', 'admin');
$I->logout();
$I->login('davert','123456');
$I->seeInCurrentUrl('/admin');
?>

AdminSteps class inherits from WebGuy class, thus you have common actions from modules, as well as newly defined customized actions like createUser, login, logout in your tests.

StepObjects are now in Guides too.

Groups && Extensions

Now it is possible to include 3rd party code into Codeception. Current options are pretty limited, you can extend Codeception only by listening to its internal events. Why do you need that? Not sure. But check out our Notifier extension that we prepared to demonstrate the power of extensions. Also you can develop your own alternative output formatter.

Group Classes are special extensions, that listen to events from a tests of a specific group. Thus, they are very if some tests require common environment setup. Group classes are also good for loading fixtures.

Here is the sample group class:

<?php
class AdminGroup extends \Codeception\Platform\Group {

    static $group = 'admin';

    public function _before(\Codeception\Event\Test $e)
    {
        $this->writeln("Preparing for [admin] test...");
    }

    public function _after(\Codeception\Event\Test $e)
    {
        $this->writeln("Finishing [admin] test...");
    }
}
?>

Read more about Groups and Extensions.

Conditional Asserts

Pretty simple, yet useful feature when you want your test not to be stopped on failure.

<?php
$I->canSee('Hello World');
$I->see('Hello World');
?>

This two assertions do just the same, but if canSee fails to match 'Hello World' text on a page, it doesn't stop the test. Still failed assertion will be displayed in final report.

Guides section about that.

Assertion Failure Messages Improved

For most Framework and Mink modules we improved the error messages that happen on failures. No more mystic messages like failed asserting that 0 greater then 0. Better exceptions with better error reports.

Comments Simplified

<?php
$I['comments can be easily added to a test'];
$I['and displayed in output when executed'];
$I['and added to HTML reports'];
$I['pretty cool when you follow BDD or ATDD'];
$I['describe everything in comments and then automate them'];
?>

Minor Fixes and Improvements

• codecoverage for multiple runner is now stored into right dir, thanks piccagliani.
• header actions were added to REST module by brutuscat.
• added environment management to Symfony2 module by SimonEast.

Update

It is very important to execute "build" after the update. Also this update has lots of changes, if you have an issues with them, please report them to Github. If you have issues updating, fall back to previous version for now. We are planning to introduce more humane stability politics soon. Wait for announcements.

redownload your codeception.phar for update:

wget http://codeception.com/codecept.phar -O codecept.phar

for composer version

$ php composer.phar update