sfPHPUnit2 plugin

This repository is an unofficial copy of the svn version of this plugin on symfony-project.org.

All credits go to the original author, Frank Stelzer.

---

The sfPHPUnit2Plugin is a symfony plugin that adds basic functionality for unit and functional testing with PHPUnit.

Symfony 1.x provides lime as default testing framework, but this does not match to every company's testing guidelines. This plugin provides several tasks for generating PHPUnit test cases and for executing them. It mimics the lime usage, so that switching from lime tests is quite easy. This plugin is optimized for sf 1.4 projects, but with some tricks it works also for sf 1.2.

The new plugin version supports generation and execution of selenium tests. Those tests are somehow an extension of functional tests but are handled independant from existing unit or functional tests. Developers who only want to run the normal native functional tests do not have to worry about the selenium handling.

Requirements

• a symfony version greater equal 1.2 is required
• a special compatibility task has to be run for sf 1.2 projects (see phpunit:generate-compat below)
• the PHPUnit command-line test runner has to be available as phpunit in the command line (PHPUnit is not bundled with this plugin)
• PHPUnit 3.4 is required for running all tests, otherwise this plugin is independant to the PHPUnit version

Installation

This plugin is marked as beta currently. Therefore the stability option has to be added to the plugin installer

    $ ./symfony plugin:install --stability=beta sfPHPUnit2Plugin

Generate test cases

Unit tests

Generating a test case for a unit test:

    $ ./symfony phpunit:generate-unit <name>

Creates a new file in test/phpunit/unit/<name>Test.php

An additional task for symfony 1.2 projects has to be run which creates special bootstrap files

    $ ./symfony phpunit:generate-compat

This task has to be called at the very first time only.

Functional tests

Generating a test case for a functional test:

    $ ./symfony phpunit:generate-functional <application> <controller_name>

Creates a new file in test/phpunit/functional/<application>/<controller_name>ActionsTest.php. This generation is not done automatically when a new module is generated and has to be called by hand currently.

Selenium tests

Generating a test case for a selenium test:

    $ ./symfony phpunit:generate-selenium <application> <controller_name>

Creates a new file in test/phpunit/selenium/<application>/<controller_name>ActionsTest.php. This generation is not done automatically when a new module is generated and has to be called by hand currently.

Options

• overwrite: An existing test case is not overwritten by default. Overwritting is enabled with this option.
• dir: A subfolder the generated test case should be saved in.
• template: A template name to use for this test. Templates files should be placed in "data/sfPHPUnitPlugin/template//"
• plugin: A plugin name, without base dir (like sfPHPUnit instead of sfPHPUnitPlugin), to generate a test for this plugin.

Examples

    $ #test/phpunit/unit/somesubfolder/SomeToolsTest.php
    $ ./symfony phpunit:generate-unit --dir="somesubfolder" --overwrite --template="my_own_template" SomeTools

    $ #test/phpunit/functional/frontend/homeActionsTest.php
    $ ./symfony phpunit:generate-functional frontend home

    $ #test/phpunit/selenium/frontend/homeActionsTest.php
    $ ./symfony phpunit:generate-selenium frontend home

    $ #plugins/anExamplePlugin/test/phpunit/unit/SomeToolsTest.php
    $ ./symfony phpunit:generate-unit --plugin=anExample SomeTools

Usage

Usage

Unit tests

The unit test given in the official documenation would look like this:

<?php
require_once dirname(__FILE__).'/../bootstrap/unit.php';

class SomeTest extends sfPHPUnitBaseTestCase
{
  protected function _start()
  {
    $this->getTest()->diag('test is starting');
  }

  protected function _end()
  {
    $this->getTest()->diag('test is ending');
  }

  public function testStrtolower()
  {
    $t = $this->getTest();

    // strtolower()
    $t->diag('strtolower() ...');
    $t->isa_ok(strtolower('Foo'), 'string',
	    'strtolower() returns a string');
    $t->is(strtolower('FOO'), 'foo',
	    'strtolower() transforms the input to lowercase');
    $t->is(strtolower('foo'), 'foo',
	    'strtolower() leaves lowercase characters unchanged');
    $t->is(strtolower('12#?@~'), '12#?@~',
	    'strtolower() leaves non alphabetical characters unchanged');
    $t->is(strtolower('FOO BAR'), 'foo bar',
	    'strtolower() leaves blanks alone');
    $t->is(strtolower('FoO bAr'), 'foo bar',
	    'strtolower() deals with mixed case input');

    $this->assertEquals('foo', strtolower('FOO'));
  }
}

The getTest method returns a sfPHPUnitTest instance which mimics the lime interface. This mechanism makes moving from an existing lime test quite easy. Of course you can call the native PHPUnit API directly for making assertions. The base class for this test case is using the setUp and tearDown methods of PHPUnit for doing something just before and after every test. When you need some custom code during those test phases, please use the according _start and _end methods.

Functional tests

Here some content of a generated functional test:

<?php
require_once dirname(__FILE__).'/../../bootstrap/functional.php';

class functional_frontend_homeActionsTest extends sfPHPUnitBaseFunctionalTestCase
{
  protected function getApplication()
  {
    return 'frontend';
  }

  public function testDefault()
  {
    $browser = $this->getBrowser();

    $browser->
      get('/home/index')->

      with('request')->begin()->
        isParameter('module', 'home')->
        isParameter('action', 'index')->
      end()->

      with('response')->begin()->
        isStatusCode(200)->
        checkElement('body', '!/This is a temporary page/')->
      end()
    ;
  }
}

As you can see, the main testing code is almost equal to the one of lime. This could be realized, because the browser instance is linked here to the current PHPUnit test case and not to the lime test instance. Only the way the browser instance has to be fetched is different.

Selenium tests

Selenium tests behave like functional tests with additional Selenium support. The according base class for Selenium tests extends PHPUnit_Extensions_SeleniumTestCase of PHPUnit. Please refer to the official documentation of PHPUnit and Selenium for detailed information and usage.

Generate configuration

A default configuration file for any PHPUnit test runner could be generated by this new task: $ ./symfony phpunit:generate-configuration

This generates a phpunit.xml.dist configuration file in the project's root dir. It inludes a default configuration, but you may modify this file for your project needs. This file is not generated by default during the generation of the user bootstrap files. Some developers may not like this generation and so it is optional.

The phpunit.xml.dist is quite powerful and you may change the behavior of PHPUnit completely with some additional options. For example you can enable or disable the colofur output or log the results of the test runners in a JUnit compatible file, which could be analysed by continuous integration tools like Hudson for example.

Maybe you are used to integrate phpunit.xml files in your projects. But Christian pointed out, that it is a good practise using the phpunit.xml.dist configuration file instead. The phpunit.xml.dist includes project wide configuration options. If you need individual configurations create a phpunit.xml and place your custom configuration there. PHPUnit will check the existence of a phpunit.xml file first and then it looks for the .dist file.

Important:

When a phpunit.xml(.dist) file is used in a project, the task for running all tests has to be run with this command

    $ ./symfony phpunit:test-all --configuration

otherwise the configuration file not be read by PHPUnit.

Execute test cases

Unit tests

Executing a unit test:

    $ ./symfony phpunit:test-unit <name>
    $ # equal to
    $ phpunit test/phpunit/unit/<name>Test.php

When the name parameter is not given, all unit tests will be executed!

Functional tests

Executing a functional test:

    $ ./symfony phpunit:test-functional <application> <controller_name>
    $ # equal to
    $ phpunit test/phpunit/functional/<application>/<controller_name>ActionsTest.php

Both parameters are optional. When they are not given, all functional tests will be executed.

Selenium tests

Executing a selenium test:

    $ ./symfony phpunit:test-selenium <application> <controller_name>
    $ # equal to
    $ phpunit test/phpunit/selenium/<application>/<controller_name>ActionsTest.php

Both parameters are optional. When they are not given, all selenium tests will be executed.

Options

• options: An option string which is directly passed to the command-line test runner of PHPUnit.
• dir (unit test only): The subfolder an existing unit test is located in.
• base (experimental): The base folder path where custom test cases are located in. Could be used for plugin tests for example.

Examples

Executing a unit test:

    $ ./symfony phpunit:test-unit SomeTools
    $ # equal to
    $ phpunit test/phpunit/unit/SomeToolsTest.php

Executing a unit test from a subfolder:

    $ ./symfony phpunit:test-unit --dir="somesubfolder" --options="--colors --verbose" SomeTools
    $ # equal to
    $ phpunit --colors --verbose test/phpunit/unit/somesubfolder/SomeToolsTest.php

Executing a functional test:

    $ ./symfony phpunit:test-functional --options="--colors" frontend home
    $ # equal to
    $ phpunit --colors test/phpunit/functional/frontend/homeActionsTest.php

Executing all functional tests with process isolation (PHPUnit 3.4 required):

    $ ./symfony phpunit:test-functional --options="--colors --process-isolation"
    $ # equal to
    $ phpunit --colors --process-isolation test/phpunit/functional

Executing all tests (process isolation option required!):

    $ ./symfony phpunit:test-all --options="--colors --process-isolation"

Executing all tests using custom test suites defined in the phpunit.xml(.dist):

    $ ./symfony phpunit:test-all --configuration

Executing a unit test within a plugin:

    $ # file has to be located in plugins/sfPHPUnit2Plugin/test/unit/fooPluginTest.php
    $ ./symfony phpunit:test-unit --base="plugins/sfPHPUnit2Plugin/test" fooPlugin

Customizing templates

The plugin provides customization of the used templates located in sfPHPUnit2Plugin/data/template. If a template content has to be overwritten, then add a new template file in your data dir: your_project/data/sfPHPUnit2Plugin/template. The file and folder structure has to be the same like it is in the plugin. When a template file does not exist in the project data dir, the plugin will take the original template as fallback.

For example:

Placing a file in your_project/data/sfPHPUnit2Plugin/template/unit/unit_test.tpl will overwrite the content of a unit test template. The next time a unit test is generated, the plugin will use this custom content.

Additionaly, you can use the --template option at the test generation to force usage of a template by its name, like this:

    $ ./symfony phpunit:generate-unit --template="unit_test" MyNewUnitTest

Some Hints

• Functional tests of several applications have to be run with the "process isolation" PHPUnit option (only available in PHPUnit 3.4)!
• Use the colors option of PHPUnit to get a colorful representation of your test results
• You do not like the PHPUnit syntax? Use $this->getTest() to retrieve a instance of sfPHPUnitTest, which mimics the lime-like interface!
• Use the _start and _end methods for doing something just before and after a test (please do not overwrite the setUp and tearDown methods)!
• implement the getApplication method in your unit test and call getContext afterwards for creating an according sfContext instance

Snippets

Loading fixtures in your test:

Doctrine:

  protected function _start()
  {
    new sfDatabaseManager(ProjectConfiguration::getApplicationConfiguration('frontend', 'test', true));
    Doctrine_Core::loadData(sfConfig::get('sf_test_dir').'/fixtures');
  }

Propel:

  protected function _start()
  {
    new sfDatabaseManager(ProjectConfiguration::getApplicationConfiguration('frontend', 'test', true));
    $loader = new sfPropelData();
    $loader->loadData(sfConfig::get('sf_test_dir').'/fixtures');
  }

Creating a sfContext instance in a unit test:

  protected function getApplication()
  {
    return 'frontend';
  }

  public function testContext()
  {
    $this->assertEquals('frontend', $this->getContext()->getConfiguration()->getApplication());
  }

Content of a plugin test file:

  require_once dirname(__FILE__).'/../../../../test/phpunit/bootstrap/unit.php';

  class unit_plugin_sfPHPUnit2Plugin_fooPluginTest extends sfPHPUnitBaseTestCase
  {
    public function testDefault()
    {
      $t = $this->getTest();
      // test something
    }
  }

TODO

• add complete support for plugin testing