compared with
Current by Martin de Keijzer
on Feb 14, 2011 12:56.

(show comment)
Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (126)

View Page History
{note:title=HELP WANTED!}If <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.{note} Framework.</p></ac:rich-text-body></ac:macro>

h1. Why use unit tests?
<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>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>

* Sane defaults
<ul>
<li>Sane defaults
<ul>
** default <li>default database names, usernames, passwords, etc. should not conflict with existing ones</li>
** desired [database] account restrictions and access should be included
<li>desired <ac:link><ri:page ri:content-title="database" /></ac:link> account restrictions and access should be included</li>
** include <li>include example database creation scripts for each of the tested database engines</li>
** reports <li>reports produced in less than 15 minutes on typical systems</li>
</ul>
</li>
* All <li>All tests work out of the box, with minimal configuration</li>
* Test <li>Test startups and teardowns should be "smart" &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>
* Zend_Environment <li>Zend_Environment runs first (to determine if the environment meets minimum ZF requirements)</li>
</ul>

h1. Zend Framework Testing Standards Best Practices

* Zend Framework unit tests are written for [PHPUnit|http://www.phpunit.de/].
** New install:
<h1>Zend Framework Testing Standards Best Practices</h1>
{code}
<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
// 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>
{code} <li>Upgrading:
** Upgrading:
{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ pear upgrade phpunit/PHPUnit
{code}
** Upgrading from PEAR/PHPUnit2:
{code}
]]></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>
{code} </ul>
</li>
</ul>

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

Look per browser at http://pear.phpunit.de/ and see what's the latest release...
Today for example the latest release version is http://pear.phpunit.de/get/PHPUnit-3.5.11.tgz.
Now do the following
<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>
{code}
<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
{code}
]]></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>Code coverage</h2>

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

If the beta version is relatively "stable", then try:
{code}
<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
{code}
]]></ac:plain-text-body></ac:macro>

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

{code}
<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
zend_extension=/usr/...../lib/php/extensions/no-debug-non-zts-20050922/xdebug.so

{code}
]]></ac:plain-text-body></ac:macro>

And use the "--report=<dir>" to generate HTML code coverage reports in <dir>.
<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>Generating Tests</h1>

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

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

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

h3.Before change
{code}
<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');
{code}
h3.After change
{code}
]]></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');
{code}
]]></ac:plain-text-body></ac:macro>

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

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

{code}php AllTests.php{code}
<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>Code Coverage Report</h3>
<p>To produce a web-based code coverage report go to commandline, change the active directory<br />
to either */tests* or */incubator/tests* and enter
to either <strong>/tests</strong> or <strong>/incubator/tests</strong> and enter</p>

*phpunit --report C:\temp\reports AllTests.php*
<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>Writing tests</h1>

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

h3.100% Code Coverage
<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>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>
Example: <ul>
Think of an input parsing class for numbers.
We would have to test
* no input
* whitespace input
* positive numbers
* negative numbers
* decimal numbers
* float numbers
* Strings which include numbers
* Exception thrown
<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>

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

If someone writes new tests to cover goal one or two to components for which he is not a contributor,
please write a new issue.
<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>

h2.Using the Test Helper
In the {{tests}} directories of the core and incubator are files named {{TestHelper.php}}. This script is provided to aid with general unit testing setup, such as using the proper {{error_reporting}} level, setting up the {{include_path}}, etc.
<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>

Whether you are writing a test case class that extends {{PHPUnit_Framework_TestCase}} or you are writing a full test suite, you can use a simple directive to provide this automatic setup for you. An example follows:
<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>
{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
<?php
/**
*/
require_once dirname(__FILE__) . '/../TestHelper.php';
{code}
]]></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>