Here is my quick guide on how to setup phpUnit and phpDoc for Kohana 3.
phpUnit
1. Setup
Install phpUnit using pear:
pear install phpunit
(See the PEAR site for how to install PEAR.)
Get the Kohana unittest module from http://github.com/kohana/unittest. If you aren’t using git for your repo, just clone the files (git clone http://github.com/kohana/unittest.git), get rid of the .git subdirectories and copy the module to your modules/ directory.
Follow the setup instructions on GitHub. Some tips:
It may be easiest to define an alternative default database configuration, since currently unittest does not automatically change any of the database configurations (ex. in models). Since I use a Fedora VM for development but prefer to run tests on Windows, I added the following logic to config/database.php:
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') { return array('default' => ..test config..); } else { return array('default' => ..normal config..); }
I did the same thing in bootstrap.php, selectively enabling the unittest module and changing the cache dir based on the OS. You can probably think of some way to do the same in your setup even if you aren’t using a different OS for serving HTTP requests.
2. Creating tests
Tests for application files go into the application/tests/ folder you create.
Tests for any module (inc. application, database, unittest etc.) go in the ‘tests’ folder in the module.
Tests extend Kohana_Unittest_TestCase, not PHPUnit_Framework_TestCase.
To group individual tests into modules you need to add the tests to a group for that module. The convention for group names is modules.{module_name}. This is done using the docblock @group specification (can have multiple group specifications). See Writing Tests in the repo on GitHub.
3. Fixtures
The easiest way to create fixtures is to use setUp() to set the DB, then tearDown() to clean up. You can just use the DB class, or use ORM to add the records. Example:
class WhateverTest extends Kohana_Unittest_TestCase { function setUp() { // setup the DB DB::query(NULL, "TRUNCATE `kohana_test`.`whatever`;")->execute(); $fixture_rows = array( array( 'key' => 'billing_key', 'value' => '0', ), ); // add the necessary items foreach($fixture_rows as $row) { DB::insert('whatever', array_keys($row))->values(array_values($row))->execute(); } } function tearDown() { }
There is probably a better way using a proper fixture class, but I haven’t seen one for Kohana yet.
4. Execution
You will need to specify the path to the KO3 webroot index.php as the bootstrap for phpUnit. This is because the dependencies which your code has need to be loaded by Kohana.
By default, all tests in application/tests/ will be run.
phpunit --bootstrap=index.php ./modules/unittest/tests.php
To run a specific group of tests on the cli add –group {groupname.in.testfile} between the –bootstrap switch and the path to the tests folder.
phpunit --bootstrap=index.php --group groupname.in.testfile ./modules/unittest/tests.php
phpDocumentor
Install phpDocumentor using PEAR: pear install phpDocumentor.
On Windows, if you use paths with spaces in them it is easiest to make sure that phpDocumentor is in the php include path (edit php.ini if necessary), and invoke php while passing the phpdoc file directly (see below for example).
You will probably only want to generate API docs for application/, perhaps selectively adding a few modules. And you probably want to exclude: application/vendor/, application/logs/, application/views/, application/bootstrap.php and application/config/ from the API documentation.
Remember that phpDocumentor does not support multiple option specifications: you have to join the paths with a comma. Furthermore, remember to have the directory separator character at the end of directories to trigger the correct interpretation.
Kohana3 uses a number of custom tags, so you will want to exclude those. Here is a sample run:
php "c:\Program Files (x86)\PEAR\phpdoc" --directory application/ --ignore application/vendor/,application/logs/,application/views/,application/bootstrap.php,application/config/ --target doc/api --customtags type,default,constructor,chainable,class,namespace,module,group
There are a few options that may also prove useful:
–parseprivate causes private methods to be shown
–output HTML:frames:earthli changes the output to earthli, which I like.
–undocumentedelements Adds warnings to errors.html for undocumented elements.
