README

# sfPHPUnit2 plugin #

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/&lt;name&gt;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/&lt;application&gt;/&lt;controller_name&gt;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/&lt;application&gt;/&lt;controller_name&gt;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** (unit test only): A subfolder the generated test case should be saved in.

### Examples ###

        $ #test/phpunit/unit/somesubfolder/SomeToolsTest.php
        $ ./symfony phpunit:generate-unit --dir="somesubfolder" --overwrite 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

## Usage ##
It is recommended to call the test classes directly with the phpunit command line runner.
This way is more powerful and handy than using a symfony task for it.

### Unit tests ###
The unit test given in the [official documenation](http://www.symfony-project.org/book/1_2/15-Unit-and-Functional-Testing#chapter_15_unit_tests "Unit and Functional Testing") 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](http://www.phpunit.de/manual/current/en/selenium.html) and [Selenium](http://seleniumhq.org/docs/) 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](http://www.phpunit.de/manual/3.4/en/appendixes.configuration.html) 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](http://hudson-ci.org/) for example.

Maybe you are used to integrate phpunit.xml files in your projects. But [Christian](http://test.ical.ly/2010/08/24/best-practice-how-to-ship-phpunit-configuration/) 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
        $ # equal to
        $ phpunit test/phpunit

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.

## Some Hints ##
  * **Functional tests of several applications have to be run with the "process isolation" PHPUnit option (only available since PHPUnit 3.4)!**
  * Switch the controller to "sfPHPUnit2FrontWebController" for the test environment when you use process isolation in combination with functional test. Otherwise uncaught exception will not be handled correctly by PHPUnit (Exception thrown without a stack frame in Unknown on line 0 ...).
  * 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
        }
      }

## Contributors ##
  * Gordon Franke
  * Jan Molak

## TODO ##
  * add complete support for plugin testing