We are pleased to make a special announcement, today. From now on the development of Codeception will be sponsored by 2amigOS!, a web development and consultancy company from Miami. They are widely known in the Yii community by their open source works. They use Codeception in their daily development, as well as recommend it to their clients. They decided give back to provide a sponsorship to our testing framework.

What does this mean for the Codeception project? You can be certain that nothing is changing with the development process or license, and Codeception will remain absolutely free and open source with MIT license. Essentially, this means that now, Michael Bodnarchuk "Davert", will get more time to devote to it to make it even more robust.

What does this mean for you, Codeception users? This means that Codeception is making a serious step towards becoming a professional testing tool. However, being professional also requires some reliability and more efficient support, marketing, and business strategy. Certainly, that is not a task one person (or Codegyre developer team) could handle. With this partnership we will improve the support, documentation and definitely will start to bring more features to this product. Also, as some point in the future we will launch commercial support and trainings (for those who are interested in them).

The only term 2amigOS! have asked for their sponsorship was a small refactoring in code. You will need to update your tests according to this example:

<?php
// for acceptance tests
$I = new WebAmigo($scenario);

// for functional tests
$I = new TestAmigo($scenario);

// for api tests
$I = new ApiAmigo($scenario);
?>

Just kidding :) Instead of renaming Guy classes, we decided to thank 2amigOS! by putting their logo on the site to show their support and dedication.

We are looking forward to some great new things and a good future, so... Please spread the word about Codeception. Encourage your friends to try it, and add your company to this list. Thanks for those who are already using it, and special thanks for those of you who contribute.

P.S. Btw, don't miss Nettuts+ course on Codeception which started today. Take your seats and say thanks to Jeffrey Way for it.

In this blogpost we will try to figure out how to get faster into the testing. What tests to write at first? Let's say we already have a project and we didn't practice TDD/BDD developing it. Should we ignore testing at all? Definitely no. So where should we start then?

Meet the Pyramid

There is a very basic schema for proper the testing suite. It is called the Pyramid of Testing.

This concept was originally proposed by by Mike Cohn, his book "Succeeding with Agile" and became the one of the fundamentals in testing. In this schema all tests are divided into 3 or 4 layers and states the dependencies for those layers. You won't build a pyramid having only top and bottom of it. That means that your acceptance tests depend on your integration (functional) tests, and they depend on unit tests. Also pyramid shows you the proportion for tests that should be written. You should have lots of unit tests, some functional, and few of acceptance.

When to skip unit tests.

In web development with PHP we are not building the software from scratch. We use frameworks and content management systems and to create web sites and applications on top of them.

For platforms like Drupal or Wordpress we can't unit test our application at all. And even modern PHP frameworks may not help you with unit testing. Tracking and mocking dependencies, especially in controllers can become a pain. If you feel that it takes for you too long for writing unit tests, skip them for now.

There is nothing wrong to start testing with no unit test actually written. Inability to write unit tests, should not be excuse for not testing at all. If you develop web application with CMS or framework, you can rely on its internals, thus you can assume that you are already using its unit tests in your pyramid's basement.

If you can't figure out how to test the most important application parts on the unit level, try to cover it with functional tests.

Getting it tested with Codeception

If you are new to Codeception, check our guides.

We recommend to start with covering most crucial parts of your application with functional tests, if your framework supports them. Be aware, that stability of framework modules in Codeception can vary. If Codeception does not have a module for your framework, you can stick to PhpBrowser. Actually you should think of it as level of functional / integration testing. It does not work with GUI, it does not require a browser, thus it runs much faster then acceptance tests. So if you don't plan to use one of the frameworks module, place PhpBrowser to functional testing suite and use TestGuy to manipulate it.

When your most important functionality is covered with functional tests, you should cement the basement with unit tests and build a top with Selenium acceptance tests.

At first try to keep tested the most important parts of your application. If you can do that with units, you are the hero! If not, try to do it on functional testing level, if still no, PhpBrowser is your choice. But please do not start testing with Selenium tests!

Then you should extend your testing suite to cover more and more parts. Please remember the pyramid, and use code coverage reports to track which code parts are still terra incognita.

Happy testing.

Update: Yii2 module was included in release. See details below.

It was a one-month release sprint and probably this release took much longer then we expected. 1.6.3 release introduces lots of features, internal unit tests, and internal refactorings. Please take a cup of coffee because we prepared a long story of features you can try in 1.6.3.

The major internal change you should be aware of is upgrade to Symfony Components 2.3. This may introduce some instability, or conflicts (if you use previous Symfony version), but the good news are that: Symfony 2.3 is LTS, so we are going to stay on this version for a long time.

One-Runner

This feature was expected by Symfony2 users, as well as other developers who uses several independent applications in a project (as Symfony bundles are). From now on you are not limited to execute tests from only one directory. In Codeception 1.6.3 you can create a meta-config and make it to point to other codeception test configs:

include:
  - frontend
  - admin
  - api/rest
paths:
  log: log

In this codeception.yml we include tests configs from frontend, admin, and app/rest directories. By executing tests from it, we will launch all test suites from this applications.

More about it...

Symfony2 users now can create a test suite for each bundle they have and then execute all tests in meta config.

Namespaces

If you decided to use a multiple-config option, the first issue you get is conflict of Helper classes and Guy classes. It's natural to use namespaces to separate those classes of multiple applications. From now on, you can assign a namespace for your test classes.

Facebook Module

Thanks to Tiger-seo we got a module that might be very handy for all developers that work with Facebook API.

<?php
$I = new ApiGuy($scenario);
$I->am('Guest');
$I->wantToTest('check-in to a place be published on the Facebook using API');
$I->haveFacebookTestUserAccount();
$accessToken = $I->grabFacebookTestUserAccessToken();
$I->haveHttpHeader('Auth', 'FacebookToken ' . $accessToken);
$I->amGoingTo('send request to the backend, so that it will publish on user\'s wall on Facebook');
$I->sendPOST('/api/v1/some-api-endpoint');
$I->seePostOnFacebookWithAttachedPlace('167724369950862');
?>

Don't leave your Facebook applications untested! With this module you can log in as test user and perform interactions using REST API or HTTP calls.

Facebook Module Referenace

Helper Customizations

Before 1.6.3 Helpers was loaded with simple include_once call. I.e., there was no other option then to load them from tests/_helpers directory. In 1.6.3 we replaced this call with autoloader, and also we added a global _bootstrap.php file in which you can prepend any code before helpers are loaded.

More about autoloading Helpers.

Also in 1.6.3 you can customiza which methods of module or helper should be imported into Guy class. In other words, you can enable or disable module methods. If your helper is extended from one of standard modules, you can disable usage of inherited methods and implement them on your own. It is especially useful if you want to rename parent class methods:

<?php
class SecondDbHelper extends Db {
    public static $includeInheritedActions = false;

    public function seeInSecondDb($table, $data = array())
    {
        $this->seeInDatabase($table, $data);
    }
}    
?>

More on helper customization.

Stubs with Mock matchers.

Codeception's utility Stub class got lots of improvements by svsool. Mock matching was also added into it, thus you may use shorter mock syntax in your unit tests:

<?php
use \Codeception\Util\Stub;
// example 1
$mock = Stub::makeEmpty('SomeClass', array(
    'trackInvocationCount' => 
     Stub::once(function() {return true})),
     $this);

$mock->trackInvocationCount();

// example 2
$mock = Stub::makeEmpty('SomeClass', array('methodNeverCalled',  Stub::never(), $this);
?>

Complete reference is coming soon.

Execute Call

In case you need to execute custom code in a test, you can now use the execute method for that:

<?php 
$I->execute(function() {
  DB::updateCounters();
});
?>

execute method is declared in Guy class itself, thus it can be used anywhere without attaching a module. As you know, Codeception tests files are included 2 times: one for parsing and for execution. Calls inside execute method will be triggered only on test execution.

Thanks korotovsky for implementation.

Yii2 module

Yii framework hits its second major version. Yii 2.0 was developed with testing in mind. Despite the fact that Yii 2.0 is still in its early days, we got a working Yii2 module for it. Unlike most of framework modules of Codepception, this one was created by Yii core developer qiangxue.

We are excited of collaboration with Yii Framework core team. And we wish them Yii 2.0 project to hit stable release soon.

Various Ehancements and Fixes.

• --no-colors runner option by igorsantos07.
• fix to double text in generate:scenarios.
• ZF1 sessions and auth helpers fixed by brutuscat
• seeInDatabase can check that table is empty with: seeInDatabase('empty_table') by igorsantos07.
• ZombieJS updates by synchrone.

additionally we had lots of fixes to Db module and its drivers. Sorry, we can't list all of them here.

As it was said we had internal refactorings, to make code stable and clearer. Soon we plan to publish a complete blog on Codeception internals.

Update

redownload your codeception.phar for update:

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

for composer version

$ php composer.phar update

Release sponsored by 2AmigOS

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

This relese fixes two reported bugs.

• using see commands on pages with <!DOCTYPE
• using see commands with non-latin characters. PhpBrowser, Selenium, Frameworks modules were updated.

Please update your version via PEAR:

$ pear install codeception/Codeception

or download updated Phar package. It's important to update Codeception now.

In next releases an automatic updater will be added.

As you may know, Codeception a BDD-style testing framework has tools for cleaning up tested database between tests. This week tools for database repopulation in Codeception were improved and it's usage was covered in new chapter of Guides. To get your database populated before tests, just provide an SQL dump and set up PDO connection. For functional and unit testing best way to clean up your database faster is not to pollute it at all. All database queries can be taken into transaction and rolled back at test end. This behavior is introduced within new Dbh module, and in ORM modules for Doctrine1 and Doctrine2. To speed up data repopulation in acceptance tests we recommend you to move database to SQLite.

Database repopulation is the subject of the new Guide: Working with Data was started. It explains different strategies for database cleanups and usage of fixtures in Codeception.

Codeception is now tested for loading and cleaning up SQLite, MySQL, and PostgreSQL dumps.

Bugfixes:

• configuration merged improperly (reported and fixed by zzmaster).
• steps are printed in realtime and not buffered anymore.
• asserts on html pages doesn't echo all page texts for strings longer then 500 chars.
• tests are sorted by name when loading.

Please update your version via PEAR:

$ pear install codeception/Codeception

or download updated Phar package.

This Codeception release is all about minor but useful features. Starting from 1.0.3 you will be notified on every new Codeception release from console. If you are not running tests, Codeception Cli application will check for new version and notify you if it is available.

$ codecept
UPDATE: version 1.0.3 released. See changes on: http://codeception.com.
Codeception version 1.0.2

There are new generators for empty tests: Cest and Cept files. Empty test suite can be generated too. Just check new 'generate:' commands.

Agile Documentation

But the most interesting generation feature is Agile Documentation. From now you can improve your documentation generated by DocBlox by appending test scenarios into text. With Codeception BDD approach to Unit Tests it's easy to imagine every test as usage documentation.

The concept of Agile Documentation will be demonstrated in following example:

We have a sample static method for creating an entity Group. Which can be group of people in social network, for example. This method uses Doctrine 2 as ORM.

<?php
class Group {
    
    // This creates new group by user
    public static function create($name, $founder_id)
    {        
        $em = self::$entityManager;

        $group = new \Model\Group;
        $group->setName($name);
        $group->setUser($em->getRepository('Model\User')->find($founder_id));
        $em->persist($group);
        $em->flush();

        return $group->getId();
    }
}
?>

This method requires Id of user who creates group and group name. Here is test for this function:

<?php
    public function create(\CodeGuy $I)
    {
        $user_id = Fixtures::get('valid_user')->getId();

        $I->wantTo('create group');
        $I->executeTestedMethodWith('DemoGroup', $user_id)
            ->seeInRepository('Model\Group', array('name' => 'DemoGroup', 'user_id' => $user_id, 'type' => 'group'))
            ->seeResultIs('int');
    }
?>    

This test is translated into documentation for Group::create method.

With this method I can create group

If I execute \Service\Group::create("DemoGroup",1)
I will see in repository "Model\Group",{"name":"DemoGroup","user_id": 1, "type": "group" }
I will see result is "int"

Codeception scans for all Cest files and for all classes passed to DocBlox. When tests match the function in documentation the test is processed and appended into function description.

To start using Codeception with DocBlox you should use the same project root for both projects, i.e. codeception.yml and docblox.xml should be in one directory. Include plugin into docblox.xml:

    <plugins>
        <plugin path="{FULL-PATH-TO-PEAR}/Codeception/plugins/DocBlox/Codeception">
        </plugin>
    </plugins>

As you see, you should specify path to PEAR explicitly. This is DocBlox limitation. Plugins can be either local or provided with DocBlox distribution. I'm not sure how to deal with current Codeception plugin for DocBlox, so I asked this question on GitHub. I hope in near future a better solution will be proposed.

Bugfixes

• replaced suppressed errors with error elimination (thanks to jonphipps)
• fixed scenario generations
• fixed generation of html reports

Please update your version via PEAR:

$ pear install codeception/Codeception

or download updated Phar package.

This release brings a real behavior driven development to Codeception. Before that we talked about testing in BDD-style, but nothing about real development by behavior. There were just few changes made in code. More changes are coming to documentation.

Specifications

With Behavior Driven Development you start development of class by writing it's specifications. Specifications are written as methods of Cest class and start with 'should' word.

<?php

class EventMachineCest {

    $class = 'EventMachine';
    
    function shouldHaveInitialState() {}   
    function shouldMoveBetweenTransitions() {}
    function shouldMoveBetweenTransitionsOnCondition() {}
}
?>

The EventMachine class in example above is not written, but we've already defined what to expect from it. After a basic requirements are specified we can take a deeper look into it and describe how it should be used. From this point your specifications become a valid Codeception tests.

<?php
class EventMachineCest  {

    $class = 'EventMachine';

   /**
   * @doc getState
   */
    function shouldHaveInitialState(CodeGuy $I)
    {
        $em = new EventMachine;
        $I->executeMethod($em, 'getState')
            ->seeResultEquals('initial');
    }
}
?>

For full EventMachineCest example see my Gist on Github.

Codeception generates a pretty good documentation with DocBlox based on your scenario. The @doc annotation marks that a getState method documentation will be updated by current test scenario.

I want to have initial state

I execute method $eventMachine, 'getState'
I see result equals 'initial'

Scenarios

For making acceptnace tests usable for writing Stories we've added 2 new methods. It's am and lookForwardTo which represent 'As a ...' and 'So that' definitions from Story.

<?php
$I = new WebGuy();
$I->am('regular site user');        // As a regular user
$I->wantTo('create my blog page');  // I want to create my blog page
$I->lookForwardTo('get a cool blog here');  // So that I get a cool blog

$I->expect("blog can't be created twice");
$I->expect("blog has RSS feed");
$I->expect("am administrator of this blog");
?>

After that Cept can be extended in a valid Cept file. Refer to this Gist demonstrates for example.

Bugfixes

• seeLink and dontSeeLink for acceptance tests were fixed. Thanks to Kanstantsin Kamkou.
• comments are displayed in output as well as actions.
• Selenium docs updated.

Please update your version via PEAR:

$ pear install codeception/Codeception

or download updated Phar package.

Almost every week Codeception gets a new release. I think it's quite good tempo. Every release contains not only bugfixes but a new features too. I'm satisfied but today's release, because all changes were made by new Codeception contributors. Thank you, guys!

Features

A new module for Social Engine was created by Artem Kovradin. He took the code of Zend Framework module and adopted it for Social Engine, which is build with powered by Zend Framework. With now on, you can simply test you social networks built on top of Social Engine.

Bugfixes

• Windows command line problem solved, thanks to Morf
• There were problem in functional tests for forms with no submits ('<input type="submit"'). This bug was pointed by svsool.

Also there were some encoding issues, but they are solved easily if you make sure your code and site has a UTF-8 encoding.

Thanks again to all contributors and reporters.

Please update your version via PEAR:

$ pear install codeception/Codeception

or download updated Phar package.

That was quite a long time after last version was released. This time we decided to skip version 1.0.6, just because 1.0.7 looks prettier.

With this release Codeception can be used in CI systems like Jenkins. It's very easy: you just append '--xml' option for running test and receive xml report in JUnit format stored in 'tests/_log' directory. Other popular formats like Json and TAP were added too. Here is a sample report.xml generated by Codeception test suite:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite name="acceptance" tests="9" assertions="29" failures="0" errors="0" time="41.532108">
    <testcase file="Cli\BuildCept.php" name="test build command (Cli\BuildCept.php)" assertions="5" time="4.016982"/>
    <testcase file="Cli\GenerateCeptCept.php" name="generate sample cept (Cli\GenerateCeptCept.php)" assertions="5" time="15.401255"/>
    <testcase file="Cli\GenerateCestCept.php" name="generate sample cest (Cli\GenerateCestCept.php)" assertions="3" time="3.742880"/>
    <testcase file="Cli\GenerateScenariosCept.php" name="generate scenarios (Cli\GenerateScenariosCept.php)" assertions="3" time="3.668740"/>
    <testcase file="Cli\GenerateSuiteCept.php" name="generate sample suite (Cli\GenerateSuiteCept.php)" assertions="4" time="4.706381"/>
    <testcase file="Cli\RunWithHtmlCept.php" name="check xml reports (Cli\RunWithHtmlCept.php)" assertions="1" time="2.428402"/>
    <testcase file="Cli\RunWithJsonCept.php" name="check json reports (Cli\RunWithJsonCept.php)" assertions="2" time="2.692029"/>
    <testcase file="Cli\RunWithTapCept.php" name="check tap reports (Cli\RunWithTapCept.php)" assertions="2" time="2.459026"/>
    <testcase file="Cli\RunWithXmlCept.php" name="check xml reports (Cli\RunWithXmlCept.php)" assertions="4" time="2.416413"/>
  </testsuite>
</testsuites>

Currently this reports are not perfect as for different file formats and you may lack some important information. For this cases, please create issues on GitHub or in Q&A section.

Thanks to Nikita Groshin new module for Kohana Framework integration was added. Please, check it out for your Kohana projects and leave a feedback.

Bugfixes

• with new release of ZF2 bug with empty cookie parameter was fixed
• bootstrap was not loaded for Test files
• fails on generation of html reports

Also there were some encoding issues, but they are solved easily if you make sure your code and site has a UTF-8 encoding.

Thanks again to all contributors and reporters.

Please update your version via PEAR:

$ pear install codeception/Codeception

or download updated Phar package.

Also you should update Mink, as it uses Zend Framework 2 beta 3 now for PHP browser. All Codeception dependencies can be updated with a single command.

$ codecept install

From this release you can install Codeception via Composer. If you have fucked up with PEAR it's a good idea to try out brand new Composer. It allows you to install Codeception with all it's dependencies, even PHPUnit, without any usage of PEAR.

If you already use Composer add this lines int your composer.json to and update packages.

    "require": {
        "Codeception/Codeception": "*"
    },
    "repositories": {
        "behat/mink-deps": {
            "type": "composer",
            "url":  "behat.org"
        }
    }

From now on you can run Codeception with

php vendor/bin/codecept

If you are new to composer but you are troubled with PEAR, the installation guide is updated for you.

Except this significant (but simple change) this release is all about bugfixing.

With the help of GitHub users ilex and nike-17 Kohana module was improved. Do you want to have a module for other frameworks? Maybe Yii, Fuel, CodeIgniter or Zend Framework 2? It's really simple. You just need to write a proper connector and you can go with performing functional tests inside your application. Check the [Functional Testing]http://codeception.com/docs/05-FunctionalTests) section of documentation.

And some good news about documentation! Jon Phipps has done a great job on editing the docs. Soon it will be published here. I know my English is not perfect. So I really appreciate any help in editing and reviewing documentation or blog posts.

Thanks to Sergii Grebeniuk for a small patch on autoloading.

There was not too much unique features in this release. Maybe you have some ideas on what should be improved?

This evening I released Codeception 1.0.9. The most important thing you may notice is documentation. It's just better. It was improved by Jon Phipps. Better phrasing goes to better understanding, right? But let's move on to see the actual new features.

Zombies are coming!

Two new modules were intoduced by Alexander Bogdanov @synchrone. It's new Selenium2 module and ZombieJS.

Ok, you may know about Selenium. But what is the purpose of Zombie?

Tools like ZombieJS, (PhantomJS, and more) are built in order to run tests without a browser. And so they are called headless. They don't require a browser window to start, they don't show any interactions on screen.

Why do we need browser for testing web applications? Only browser-based javascript engines can run all the client side code. ZombieJS is one of them, taken from browser and produced as a standalone tool. It's built with Node.js and requires Node.js, NPM, a C++ compiler and Python to install. Check out it's official site for more information.

Thanks to Mink from now on you can write ZombieJS tests inside Codeception just like tests for other cases.

Don't run too fast!

Selenium and Selenium2 modules was updated with the new delay option. If Selenium performs actions faster the user, and javascript just can't catch it it, you can slow down the execution by setting the delay param. It's set in milliseconds and will perform pauses after each step in scenarios.

Composer Tricks

Seems like the PHP WebScrapper Goutte (which is used by PHPBroser module) has a new backend now. It has moved from Zend Framework 2 libraries to new lightweight HTTP client Guzzle. So, no more Zend dependencies and long stack trackes. This change doesn't affect PEAR users, cause this change arrive in PEAR packages yet.

Thanks again to all contributors and reporters.

Please update Codeception version via PEAR:

$ pear install codeception/Codeception

or via Composer

$ php composer.phar update

Codeception testing framework got significant improvements during last week. The first and the major one is that you don't even need PEAR and Composer to execute tests. Only one file codecept.phar required. This might save your time and mind of your testers.

So Installation is much simplier now:

1. Download archive.

2. Execute it with PHP php codecept.phar

Now you can start generating a test suite with php codecept.phar bootstrap or execute existing tests with php codecept.phar run.

Documentation section was created. New section Reference was added. There you can review Codeception commands and configuration values.

But the most cool stuff is new module for testing web services!

Modules for SOAP and REST were added recently. You know it's always hard to test the API manually. So why not to automate it?

This API modules keeps simple manner in describing tests. Take a look at sample REST test.

<?php
$I = new ApiGuy($scenario);
$I->wantTo('create a new user by API');
$I->amHttpAuthenticated('davert','123456');
$I->haveHttpHeader('Content-Type','application/x-www-form-urlencoded');
$I->sendPOST('/users', array('name' => 'davert' ));
$I->seeResponseCodeIs(200);
$I->seeResponseIsJson();
$I->seeResponseContainsJson(array('result' => 'ok'));

And here goes a sample SOAP test:

<?php
use \Codeception\Utils\Soap;

$I = new ApiGuy($scenario);
$I->wantTo('create a new user thorough API');
$I->haveSoapHeader('Auth', array('token' => '123123'));
$I->sendSoapRequest('CreateUser', Soap::request()
    ->User
        ->Name->val('davert')->parent()
        ->Email->val('davert@codeception.com');
);
$I->seeSoapResponseIncludes(Soap::response()->result->val(1));

Ok, the one thing you may have noticed. We are working with JSON in first case and XML in second. But there is no JSON or XML in code! Well, we could have used it, but we didn't. Just because we can use PHP to set data in this formats. Json is built from PHP arrays and for XML is used jQuery-like styled XMLBuilder class. But you could possibly add a raw json or XMl into your tests. No problems with that!

Modules themselves are already documented and tested. Soon a complete guide on WebService API testing will be added.

The other thing worth to mention is new finalizers in test scenarios. If you need to execute code after test is finished and you don't want to put it in helper use the $scenario->finilize method. See it's usage example in new Manual Cleanup section of Guides.

This is Codeception 1.0.11. Download new version to run tests or update

via PEAR

$ pear install codeception/Codeception

or via Composer

$ php composer.phar update

Hi, that's been a while from the last release. But still Codeception is evolving. And today's release notes I'm going to start with some thoughts on Codeception installation strategy.

For a long time a PEAR was the primary method for install. It had some issues and develoeprs got stuck with it. Nowdays alternative is a [Composer[(http://packagist.org)] which Codeception uses too. But nevertheless we consider it a bit complex too. Codeception is tool where everything is kept simple. We are trying to make it work even for junior developers and testers. So our primary goal is to provide a standalone version 'codecept.phar' which was introduced recently. In future version we will try to make it autoupdate itself (as Composer does).

It's really cool cause it simplifies integration with CI systems and has less requirements to your PHP environment. Right now Codeception phar archive includes Symfony Components, Mink, PHPUnit in one file. So if you ever wanted to run PHPUnit tests without PEAR, the Codeception can be used that way too.

The major feature is related to current installation strategy. We finally added custom assertions to modules and user helper classes. Before that you should have used PHPUnit's static methods for assertions. But now you can just write this->assertXXX in a helper class.

In next example we connect PhpBrowser module to helper and use assertion to check a menu exists for current user.

<?php
class WebHelper extends \Codeception\Module {

    function seeEditingToolsMenu()
    {
        $content = $this->getModule('PhpBrowser')->session->getPage()->getContent();
        $this->assertContains('<a id="menu" href="#">Edit Post</a>',$content);
    }

}
?>

The Helpers section in Guides was totally rewritten to represent this change and provide more examples.

In this release a new module WebDebug was intorduced. It provides means to make screenshots with a single command. In case a screenshot can't be saved, it tries at least save the HTML response to file. After the test you can review all saved files to see what actually happened during test.

Thanks to Andrey Popov for contributions.

Bugfixes

• click method for frameworks now accepts CSS selectors.

This is Codeception 1.0.14. Download new version to run tests or update

via PEAR

$ pear install codeception/Codeception

or via Composer

$ php composer.phar update

Hi, last week Codeception got it's first major update. Welcome the Codeception 1.1. Many core classes were refactored to solve the common issues and reduce the level of dark magic inside. Only white magic left. And that's really cool 'cause you don't need to study to source code to implement your custom hooks now. Codeception is rapidly evolving to be the professional testing tool, ready to use by testers and developers through out the PHP world.

Test Execution Remastered

Did you ever were wondered why you can't receive values in test and pass it to next steps? To do something like this:

<?php
$user_name = $I->grabTextFrom('#user_name');
$I->fillField('username', $user_name);
?>

Actually, there is no any good reason for not doing so. The only reason was - the code was not designed to execute test file in runtime. The steps were recorded, analyzed, and only then they were executed, without touching the test file again. That is the source of dark magic that was removed in Codeception 1.1. This magic was awful because you didn't control the test execution. So, usage of custom PHP code in test was leading to unpredictable results. Even simple tasks was encouraged to be done in helpers, not in test code itself, to be run properly.

So what changed in Codeception 1.1? There is no magic in test execution, test file is required and executed, that's all. Still the analyzes step is not skipped, so test is run two times: first to record scenario, validate and analyze all steps, second to execute them. With that simple idea you can use ANY php code in your tests if only you define the stage when it should be executed. The additional bootstrap files should be loaded one time before the analyses:

<?php
if ($scenario->preload()) {
    require '_user_fixtures.php';
}
$I = new WebGuy($scenario);
$I->loginAs($user);
// ...
?>

And when you need something to be executed in runtime, like cleaning the fixture data, please use the following:

<?php
// ..
$I->loginAs($user);
$I->see('Hello, '.$user->name);
if ($scenario->running()) {
    $user->delete();
}
?>

In this example user is removed in the very end of scenario. $scenario->running method allows you to execute any code in the runtime. But please, always specify the stage when the custom code should be executed, or it will be executed 2 times.

In Codeception 1.0.x the build command was optional, when updating configuration. But now it's required to run every time the modules are added or removed in suite config file. That's the only new issue, but Guy-classes look much better now.

Grabbers

As the result of changed described above, you can finally return values to scenario and use them in next steps. The new grabbers commands were introduced:

<?php
$text = $I->grabTextFrom($element);
$value = $I->grabValueFrom($form_field);
$attr = $I->grabAttributeFrom($element, 'attribute');

$name = $I->grabFromDatabase('users', 'name', array('id' => 1));
// ....
?>

You can write your own grabbers. Just return values from your helper methods and you can use them in test. Please review the modules to see new commands there!

XPath Introduction

Codeception is a tool for testing, and many testers like specifying locators by XPath. CSS selectors have their limitations, so why not to use XPath in tests too? Sure, why not! You can freely use XPath selectors in your tests from now. But no new methods added for this! Really. The old methods were updated to support CSS and XPath as well. So whenever you need to pass a selector you can either pass CSS or XPath and Codeception is smart enough to guess what did you pass and how to use it.

<?php
$I->click('New User');
$I->click('#user_1 .user_new');
$I->click("descendant::*[@id = 'user_1']/descendant::a");
?>

All the methods where CSS was used were updated to support XPath. Try it!

Unit Tests

There was no common idea how to deal with unit tests in Codeception. As you know, Codeception can run standard PHPUnit tests as well as the hybrid scenario-driven unit tests. Scenario driven tests for many cases looked to complex to use. But they allowed to use Codeception modules in them. Why not to provide standard PHPUnit tests to use Codeception features? For Codeception 1.1 the new chapter of Guides describing unit tests is written. In brief: you can use the CodeGuy class inside your tests! Include any modules and use it as you need it. Use them to perform database cleanups, use them to check values in database, use them to work with file system. They are just wonderful helpers in your work.

And yep, new unit tests can be generated by command: generate:test.

Bugfixes and Minor changes

• nested array logging was done by tiger-seo
• ability to specify different configs for test execution, also done by (tiger-seo)
• ZF1 module fixes by insside

Upgrade notes.

• right after updating Codeception please run the build command.
• remove all chained method executions in your tests. The $I object can return values, not self.

Codeception 1.1 can be downloaded from site,

via PEAR

$ pear install codeception/Codeception

or via Composer

$ php composer.phar update

P.S. Documentation was updated for 1.1 version.

Good news, everyone! Codeception 1.1.2 released. And it's hard to list everything that were improved and fixed, but i will try. With the help of our active contributor tiger.seo Codeception got an AMQP module wich allows to manipulate queue engines, like RabbitMQ. You can use this module if you need to clear queues between tests. Also, new Memcache module was introduced. You can perform simple checks and use data from your Memcache storage in tests. Guys, it's very simple to contribute to Codeception. All new modules are welcome, they can grow from your local helpers and become part of this library. Just fork Codeception, add a module and send me a pull request!

UX Improvements

You should regenerate your guy-classes after this update with the build command. Rebuilt Guy-classes will contain full documentation for each method and link to the source code of underlying method. Also, with the help of tiger.seo Codeception got better PHPStorm integration. Codeception when run in PHPStorm console outputs stack traces that is recognized by PHPStorm. So you can click on any file name and move to it in IDE.

Save Scenarios as HTML

You know that there is --html option which saves results of running tests in HTML. But now you can save the test scenarios in HTML without running them. That's quite useful if you want to save test scenarios into your company's wiki. The HTML format can inserted into Confluence, for example. And now testers, managers, and developers will have the test scenarios up to date. Yep, thanks again to tiger.seo.

PEAR Updates

PEAR package was completely redesigned. Codeception is not using PEAR as a dependency manager anymore, Composer is ok. But PEAR is quite useful if you want a system-wide install, and simple call to Codeception with codecept command. PEAR package now contains all dependent modules and doesn't require PHPUnit or Mink installed anymore. That will prevent possible conflicts and reduce level of PEAR-related wtfs.

Bugs Fixed

• comments is shown again in console and in html output.
• bug with exception in printFail method.
• js files were not added to phar archive. Thanks to f0rm4t.
• fix tests filename to be presented with relative path. By tiger.seo.
• unable to send more than 1 parameters using SOAP.sendSoapRequest by lostintime
• DB module is not cleaned after the last test. By tiger.seo.

Codeception 1.1.2 can be downloaded from site,

via PEAR

$ pear install codeception/Codeception

or via Composer

$ php composer.phar update

Codeception 1.1.3 and then 1.1.4 was released during last month. In this post I will summarize the changes happened in this minor updates. The 1.1.3 version fixed one bug pointed by Nastya Ahramenko. Yep, only one bug. But it was pretty cool for me to mention it and make a release for it.

Nastya wrote:

If the web-page contains two similar links, then the second link is not opened. For example:

1. Page contains two links: "Test Link" is first link, "Test" is second link
2. Create test with the following steps

<?php
$I->click('Test Link');
$I->click('Test');

Both steps open the first link.

Actually we can discuss if it's a bug or a feature. But, it's more bug then a feature. This occur due to XPath locators in Mink and BrowserKit libraries. Codeception is a wrapper for Mink and BrowserKit, so there is no reason why it can't be done right. So, Codeception is solving this bug by seraching the strictly matched object at first, and then is trying to find it by more complex XPath locator. I.e., at first it will try to locate <a href="#">Test</a> and if it's not found will match the <a href="#">Test Link</a>.

That's all about 1.1.3

And now what about 1.1.4?

There are pretty much fixes from other contributors. Thanks for anyone sending me pull requests and patches. Here are the changes done by this awesome guys!

• ZombieJS fix for newer Mink version compatibility by synchrone.
• Codeception\Module\Unit.seeExceptionThrown doesn't fail when no exception is thrown by lostintime.
• Symfony2.1 compatibility fix and reinvention of package building by ZloeSabo.
• Various autoload fixes by flaviozantut and lostintime.
• No setProperty method in CodeGuy by ZloeSabo.
• Also, useful XPath matching methods added to SOAP
• Memcache module supports now either Memcache or Memcached lib.

Selenium2 module improvements

• Dealing with confirm and alert popups by f0rm4t.
• Methods SwitchToWindow and SwitchToIFrame added to Selenium2 module by f0rm4t.

Define Actions Beforehand

From now on it's much easier to define actions in helpers. You can write a method that is not defined yet, and then run new analyze command to append new commands to helper classes. It's quite useful when tester writes a test and needs some new actions to define. When you run

php codecept.phar analyze suitename`

you will be notified on all methods which do not exist in modules, and you will be asked to create them in helpers. Just try!

New Locator class

XPath locators are very powerful but are pretty hard to write and maintain. We decided to provide some useful functions to help writing locators better. Try new Codeception\Util\Locator for that. It will be described in next blogpost. Stay in touch.

As usual, Codeception 1.1.4 can be downloaded from site,

installed via PEAR

$ pear install codeception/Codeception

or via Composer

$ php composer.phar update

In the latest Codeception 1.1.4 new Locator class was introduced. Basically it should simplify your life in writing complex XPath or CSS locators. Right now it has minimal, yet useful functionality.

Combine

Locator can combine two locators using OR operand:

<?php
use \Codeception\Util\Locator;

$I->see('Title', Locator::combine('h1','h2','h3'));
?>

This will search for Title text in either h1, h2, or h3 tag. You can also combine CSS selector with XPath locator:

<?php
use \Codeception\Util\Locator;

$I->fillField(Locator::combine('form input[type=text]','//form/textarea[2]'), 'qwerty');
?>

As a result the Locator will produce a mixed XPath value that will be used in fillField action.

tabIndex

Do you often use the TAB key to navigate through the web page? How do your site respond to this navigation? You could try to match elements by their tab position using tabIndex method of Locator class.

<?php
use \Codeception\Util\Locator;

$I->fillField(Locator::tabIndex(1), 'davert');
$I->fillField(Locator::tabIndex(2) , 'qwerty');
$I->click('Login');
?>

href

Does the page contain link wo specified URL? Check that easily with href method of Locator class.

<?php
use \Codeception\Util\Locator;

$I->see('Log In', Locator::href('/login.php'));
?>

And that's all folks for today. We are sure the locator class will evolve to simplify writing complex locators. If you have ideas what methods should be added, post them here. Or, which is better, patch this class and send Pull Request to Github.

Codeception is PHP framework for testing web applications in BDD-style. It was started about a year ago, as a plugin for symfony1, to speed up and simplify functional testing inside the framework. But as time passed, Codeception evolved to standalone project, with support of various frameworks and engines. It's built on top of wonderful PHPUnit, but with aim for acceptance, and functional scenario driven tests. In this post we will remind why you may like Codeception and why we feel it's awesome.

1. PHP!

Yes, the first reason is PHP. If you are PHP developer it's natural you would like to write tests in PHP. Codeception provides you the best way to do so. Any IDE with code completion and syntax highlighting will help you write tests faster and without stupid syntax mistakes. Usage of PHP inside of tests unleashes the true power and control over the test flow. You can use your application classes or create testing helpers. Also you can get values (with grabbers) from results and use them in your tests. You just control everything. And yep, use everything you like from PHPUnit.

<?php
$I = new TestGuy($scenario);
$I->wantTo('launch missiles from my website');
$I->amOnPage('/launch');
$I->click('Launch Missiles!')
$I->see('Missiles launched');
?>

2. Simplicity

You know, KISS is our first principle. Even Codeception requires basic knowledge of PHP it narrows testing to using PHP DSL where all actions are defined with user's perspective. Just enter the $I-> and select action from a list and put parameters. That's how a test is written. Also add minimal configuration in YAML format, and installation by downloading a single phar archive. It's really that simple.

3. Multi-Framework and Multi-Backend

You decided to migrate your application from symfony1 to Symfony2, from Kohana to Zend? You decided to test with Selenium inside a real browser? Your tests will run inside chosen the engine, no matters what happen. Codeception using one common syntax for all the backends. Frameworks support allows you to create more complex assertion and check the internals of your application, not only the visible part.

4. Complex Tests

Here comes a QA and says: I need XPath, I need complex selectors, I need to test UI elements strictly. No problems! You can use CSS selectors, XPath locators and even combine them with Locator class. You can also test your SOAP and REST webservices, pragmatical use XMLs (defined in jQuery-like style) and JSONs (as PHP arrays). Despite Codeception tend to be simple, it can be used by QAs creating solid tests automation platform.

<?php
$I->click('New User');
$I->click('#user_1 .user_new');
$I->click('//*[@id = 'user_1']/descendant::a');
$I->see('Title', Locator::combine('h1','h2','h3'));
$I->fillField(Locator::tabIndex(1), 'davert');
$I->see('Log In', Locator::href('/login.php'));
?>

5. Data

Tests isolation is a problem. Most of testing frameworks puts it's solving to your shoulders. But Codeception tries to fetch your needs and provide Data cleanup from the box. With the Db module you can repopulate database (MySQL, PostgreSQL, ...), after each run, use SQLite (for faster testing), or just run all tests inside transaction (in functional or unit testing). Also Codeception have modules for using and cleaning Memcache and AMQP storages.

And Finally!

And just to mention, the results of tests are readable to non-technical guys. When you export result in HTML you will see the cool colored page with all passed steps described in pure English. Also test results are readable to robots: export result as XML and the CI-server (Jenkins, Bamboo) will use them.

If you are still deciding weather or not to test your application, start doing it now. And Codeception is the right tool for this.

It looks like a good time for the new release! Do you agree?

And yes, there are enough changes to announce Codeception 1.1.5. In this release we concentrated mostly on fixing bugs and improving error reporting. But the most important change, that from now Codeception uses PHPUnit 3.7. This PHPUnit version doesn't have that much BC breaks as previous one, so we hope you will not notice this change.

Some tasty features were added too. But let's start with error reporting.

• In stack trace PHP files of yours will be highlighted (if you use colors, of cource)
• No more ERROR with no descriptions, every error have stack trace and description
• Errors are displayed better, stack traces avaible only with --debug options

XML-RPC Module

Tiger SEO added just another useful module for testing XML-RPC web services. It requires 'php_xmlrpc' extension and PhpBrowser module to run. With this module you can perform XMLRPC calls and check the responses. You can review the code at GitHub or read the docs.

Minor Features and Bugfixes

• Composer package fixed
• grabServiceFromContainer method added to Symfony2 module
• REST fixes and improvements by tiger-seo
• Fix for using seeInDatabase command with PostgreSQL
• build command is not generating methods with the same names anymore
• no need to run build command just after bootstrap

BC breaks to aware of

There could be some BC breaks, you should know about. Before 1.1.5 you could start writing tests without defining a page. Codeception opened the root url "/" by default. So all actions were performed on home page. But opening the page before each test is not the best idea, especially if we test REST/SOAP web service. We just spend time for useless action. So whenever you write acceptance test, please start it with amOnPage action. This change didn't affect the functional tests (for now).

<?php 
$I = new WebGuy($scenario);
$I->amOnPage('/'); // required!
?>

Also, we did some changes for 2-steps tests loading, intrudoced in 1.1. At the first stage we read the test contents, in the next we execute it. From now on this stages are isolated, variables from preload will not pass to run. This will require loading of bootstrap file two times. Be prepared for that and optimize your bootstrap file.

As usual, Codeception 1.1.5 can be downloaded from site,

installed via PEAR

$ pear install codeception/Codeception

or via Composer

$ php composer.phar update