View Source

<ac:macro ac:name="note"><ac:parameter ac:name="title">HELP WANTED!</ac:parameter><ac:rich-text-body><p>If you have written testing standards previously, please read the guidelines below, and help author testing standards for the Zend Framework.</p></ac:rich-text-body></ac:macro>

<h1>Why use unit tests?</h1>

<p>Components will not be included in Zend Framework releases without a reasonable collection of working unit tests. This includes incubator components.</p>

<h1>Test Standard Goals</h1>

<p>We are moving towards continuous integration and are looking at having a build/test server (build docs, api docs and run tests) responding on check-in similar to CruiseControl.</p>

<ul>
<li>Sane defaults
<ul>
<li>default database names, usernames, passwords, etc. should not conflict with existing ones</li>
<li>desired <ac:link><ri:page ri:content-title="database" /></ac:link> account restrictions and access should be included</li>
<li>include example database creation scripts for each of the tested database engines</li>
<li>reports produced in less than 15 minutes on typical systems</li>
</ul>
</li>
<li>All tests work out of the box, with minimal configuration</li>
<li>Test startups and teardowns should be &quot;smart&quot; with persistent data, such that restarting the testing process works, regardless of possibly aborted previous tests. Various components may help, including Zend_Http_Server.</li>
<li>Zend_Environment runs first (to determine if the environment meets minimum ZF requirements)</li>
</ul>


<h1>Zend Framework Testing Standards Best Practices</h1>

<ul>
<li>Zend Framework unit tests are written for <a href="http://www.phpunit.de/">PHPUnit</a>.
<ul>
<li>New install:
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ pear channel-discover pear.phpunit.de
$ pear config-set preferred_state alpha
$ pear install phpunit/PHPUnit
or you may wish to install all the optional supporting packages:
$ nano /usr/local/php5/etc/php.ini // memory_limit = 32M; change this to at least 32M
// if you get a permission denied error on the ZF community server, send an email to fw-servers mail list
$ pear install --alldeps phpunit/PHPUnit
]]></ac:plain-text-body></ac:macro></li>
<li>Upgrading:
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ pear upgrade phpunit/PHPUnit
]]></ac:plain-text-body></ac:macro></li>
<li>Upgrading from PEAR/PHPUnit2:
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ pear uninstall PHPUnit2
$ pear channel-discover pear.phpunit.de
$ pear config-set preferred_state alpha
$ pear install phpunit/PHPUnit
]]></ac:plain-text-body></ac:macro></li>
</ul>
</li>
</ul>


<p>When you're having trouble installing the newest PHPUnit Version 3 and after upgrading your PEAR say that the newest PHPUnit Version 2.3.6 is already installed the following instuctions will help you</p>

<p>Look per browser at <a class="external-link" href="http://pear.phpunit.de/">http://pear.phpunit.de/</a> and see what's the latest release...<br />
Today for example the latest release version is <a class="external-link" href="http://pear.phpunit.de/get/PHPUnit-3.5.11.tgz">http://pear.phpunit.de/get/PHPUnit-3.5.11.tgz</a>.<br />
Now do the following</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ pear uninstall phpunit/PHPUnit
$ pear channel-discover pear.phpunit.de
$ pear install --alldeps channel://pear.phpunit.de/PHPUnit-3.5.11
]]></ac:plain-text-body></ac:macro>

<p>and you will have the latest PHPUnit Version installed.</p>

<p>Check your version by changing your working directory to PHP and run phpunit on command line.<br />
The actual version and help should show up.</p>

<h2>Code coverage</h2>

<p>The Xdebug package enables code-coverage reports in HTML: <code>$ pecl install</code></p>

<p>If the beta version is relatively &quot;stable&quot;, then try:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ pecl uninstall xdebug
$ pecl install xdebug-beta
]]></ac:plain-text-body></ac:macro>

<p>And edit your php.ini file:</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
; For Windows:
zend_extension=/usr/...../lib/php/extensions/no-debug-non-zts-20050922/xdebug.dll

; For Windows using precompiled binaries from http://pecl4win.php.net/ext.php/php_xdebug.dll:
zend_extension_ts="c:/php/modules/php_xdebug.dll"

; For *NIX:
zend_extension=/usr/...../lib/php/extensions/no-debug-non-zts-20050922/xdebug.so

]]></ac:plain-text-body></ac:macro>

<p>And use the &quot;--report=&lt;dir&gt;&quot; to generate HTML code coverage reports in &lt;dir&gt;.</p>

<h1>Generating Tests</h1>

<p>To test the framework the following prerequisits have to be done:</p>

<p>Change the files<br />
<strong>/tests/TestConfiguration.php.dist</strong><br />
<strong>/incubator/tests/TestConfiguration.php.dist</strong></p>

<p>For example if you want the report to be produced in the directory C:\temp\reports</p>

<h3>Before change</h3>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
/**
* PHPUnit Code Coverage / Test Report
*/
define('TESTS_GENERATE_REPORT', false);
define('TESTS_GENERATE_REPORT_TARGET', '/path/to/report');
]]></ac:plain-text-body></ac:macro>
<h3>After change</h3>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
/**
* PHPUnit Code Coverage / Test Report
*/
define('TESTS_GENERATE_REPORT', true);
define('TESTS_GENERATE_REPORT_TARGET', 'C:\temp\reports');
]]></ac:plain-text-body></ac:macro>

<p>Also,</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
ln -s /wherever/bin/phpunit ./phpunit
]]></ac:plain-text-body></ac:macro>

<h3>Commandline Failure Report</h3>
<p>To produce the report go to commandline, change the active directory to<br />
eighter <strong>/tests</strong> or <strong>/incubator/tests</strong> and enter</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[php AllTests.php]]></ac:plain-text-body></ac:macro>

<p>This can take a while. After the complete test is run, you will have a summary of completed, failed and not run tests.</p>

<h3>Code Coverage Report</h3>
<p>To produce a web-based code coverage report go to commandline, change the active directory<br />
to either <strong>/tests</strong> or <strong>/incubator/tests</strong> and enter</p>

<p><strong>phpunit --report C:\temp\reports AllTests.php</strong></p>

<p>After the tests have run, you will find the html-based report in the directory<br />
C:\temp\reports... or the directory you entered here.</p>

<h1>Writing tests</h1>

<p>Help on writing tests is very welcome.<br />
We will have 2 goals to cover.</p>

<h3>100% Code Coverage</h3>
<p>Target is to cover 100% of our code, to find codelines which are not used so they can be erased.</p>

<h3>Several Test cases</h3>
<p>Target is to test the code for different inputs, correct behavior and output.<br />
Example:<br />
Think of an input parsing class for numbers.<br />
We would have to test</p>
<ul>
<li>no input</li>
<li>whitespace input</li>
<li>positive numbers</li>
<li>negative numbers</li>
<li>decimal numbers</li>
<li>float numbers</li>
<li>Strings which include numbers</li>
<li>Exception thrown<br />
and so on...</li>
</ul>


<p>Of course the test for negative numbers will cover 90% of all codeline. But without the other tests<br />
we will not know if our classes behavior is as expected.</p>

<p>If someone writes new tests to cover goal one or two to components for which he is not a contributor,<br />
please write a new issue.</p>

<h2>Using the Test Helper</h2>
<p>In the <code>tests</code> directories of the core and incubator are files named <code>TestHelper.php</code>. This script is provided to aid with general unit testing setup, such as using the proper <code>error_reporting</code> level, setting up the <code>include_path</code>, etc.</p>

<p>Whether you are writing a test case class that extends <code>PHPUnit_Framework_TestCase</code> or you are writing a full test suite, you can use a simple directive to provide this automatic setup for you. An example follows:</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
<?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category Zend
* @package Zend_Magic
* @subpackage UnitTests
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id$
*/

/**
* Test helper
*/
require_once dirname(__FILE__) . '/../TestHelper.php';
]]></ac:plain-text-body></ac:macro>

<p>You may need additional parent directory directives (i.e., &quot;<code>../</code>&quot;), depending on how deep in the directory tree your file will be located.</p>