PHPCoverage is an open-source tool for measuring and reporting code coverage provided by the test suite of a PHP application. PHPCoverage can instrument and record the line coverage information for any PHP script at runtime.
PHPCoverage also provides an extensible reporting mechanism with a standard HTML report implemented out of the box. The default report displays the summary information about the code coverage for an application and also shows the detailed information about a file including which lines were actually executed and with what frequency. It is possible to specify the directories and files that should be included and/or excluded from a coverage measurement. Screenshots of the summary and detailed line coverage reports are available here.
PHPCoverage works on PHP 5.0 and newer and uses Xdebug Extension for gathering the coverage data.
Just expand the tarball
tar -zxvf spikephpcoverage-0.6.tar.gz
This will create a directory called spikephpcoverage-0.6 and expand all files in it. You should export an enviroment variable PHPCOVERAGE_HOME or define a constant in your test script that refers to the location of src directory and use it when including the PHPCoverage files:
$ export PHPCOVERAGE_HOME=/path/to/phpcoverage/src
OR
define("PHPCOVERAGE_HOME", "/path/to/phpcoverage/src"); require_once PHPCOVERAGE_HOME . "/CoverageRecorder.php";
This topic explains how PHPCoverage can be used to record local code coverage information. Any PHP script that runs in the same context as that of the invoker is said to run locally. In practice, if you are running tests that do not exercise PHP code through a web server, you can use the normal CoverageRecorder class. On the other hand, if your test suite contains web tests that access PHP code running in a web server (on same or different) machine, you will need to follow a different procedure for code coverage measurement.
require_once PHPCOVERAGE_HOME . "/CoverageRecorder.php"; require_once PHPCOVERAGE_HOME . "/reporter/HtmlCoverageReporter.php";
The first file is the coverage recorder class that can start and stop coverage recordings and configure parameters. The second file is the HTML Report Generator class.
$reporter = new HtmlCoverageReporter("Code Coverage Report", "", "report");
The first argument to the constructor is the title of the coverage report. The second argument is an optional style sheet name. If not specified, default style sheet is used. The third argument is the name of the directory where the report files should be generated. The directory will be created if it does not exist.
$includePaths = array("."); $excludePaths = array("test", "foo.php"); $cov = new CoverageRecorder($includePaths, $excludePaths, $reporter);
Please note that the PHPCoverage directory will always be omitted from the recordings irrespective of whether it is explicitly mentioned as an "excludePath" or not.
$cov->startInstrumentation(); ... // run tests $cov->stopInstrumentation();
Make sure that you exclude the directory containing the actual tests.
$cov->generateReport(); $reporter->printTextSummary();The report files can be accessed in the output directory specified.
If your tests are trying to exercise PHP code that is running within a web server on same or different machine, you should use RemoteCoverageRecorder to measure code coverage. You should also instrument the application code before running your tests. The actual process of instrumenting a file is straightforward. PHPCoverage files need to be included at the top and bottom of each of the application files. PHPCoverage comes with a command line utility to do this for you.
Deploy your web application into your web server. This typically involves copying the application files into a web directory managed by the webserver or creating a symlink from such directory to your application.
Execute the command line utility to instrument your application.
$ cd /path/to/application/base/dir $ export PHPCOVERAGE_HOME=/path/to/phpcoverage/location $ php /cli/instrument.php -b . file1.php file2.php ...
You need to specify your application base directory with -b option, followed by a list of files or directories or both. The application base directory is where your index.php is stored. PHPCoverage files will be copied to this directory and need to be accessed over HTTP to initialize code coverage measurements. instrument.php also supports following options:
The undo option can only uninstrument files that were instrumented with this script. After this step, make sure that two files phpcoverage.remote.top.inc.php and phpcoverage.remote.bottom.inc.php have been copied to your application base path. Also, the instrumented files should include these two files at the top and the bottom.
addTestFile('TestMainLinks.php'); // PHPCoverage includes require_once dirname(__FILE__) . "/phpcoverage.inc.php"; require_once PHPCOVERAGE_HOME . "/remote/RemoteCoverageRecorder.php"; require_once PHPCOVERAGE_HOME . "/reporter/HtmlCoverageReporter.php"; $cov_weburl = $weburl . "phpcoverage.remote.top.inc.php"; // Initialize RemoteCoverageRecorder file_get_contents($cov_weburl . "?phpcoverage-action=init&cov-file-name=" . urlencode("phpcoverage.data.xml") . "&tmp-dir=". urlencode("/tmp")); // Run the simple test web test suite $testsuite->run(new TextReporter()); // The coverage data is available in xml form at following url // You may download this file and save it locally for debugging $xmlUrl = $cov_weburl . "?phpcoverage-action=get-coverage-xml"; // Configure reporter, and generate report $covReporter = new HtmlCoverageReporter( "MyApp Web Test Code Coverage", "", "php-coverage-remote-report"); $excludePaths = array("../"); // Set the include path for the web-app // PHPCOVERAGE_APPBASE_PATH is passed on the commandline $includePaths = array(realpath($PHPCOVERAGE_APPBASE_PATH)); // Notice the coverage recorder is of type RemoteCoverageRecorder $cov = new RemoteCoverageRecorder($includePaths, $excludePaths, $covReporter); // Pass the XML data url to generateReport function // Alternatively, you can pass the complete file path of a local file here. // The second parameter signifies that this is a url stream and an XML string $cov->generateReport($xmlUrl, true); $covReporter->printTextSummary("php-coverage-remote-report/report.txt"); // Clean up file_get_contents($cov_weburl . "?phpcoverage-action=cleanup"); ?>
Note that calls are made to the phpcoverage.remote.top.inc.php file over HTTP to intialize coverage recorder object. Following points distinguish remote code coverage measurement from local one:
Recent versions of PHPCoverage already come with a pre-compiled Xdebug shared library (for 32-bit Linux) or DLL (for Windows). For most Linux and Windows versions they should work right out of the box. In that case, proceed to configuration section below.
If they don't, you may have to compile one for yourself. Doing so is very simple and is outlined below.
The steps outlined here are for PHP 5 installed along with SpikeSource Core Stack. They should be fairly similar for other PHP installations.
Download the Xdebug 2.x tar ball (xdebug-2.0.0beta2, as of this writing) from Xdebug download page.
$ tar -xzf xdebug-2.0.0beta2.tgz $ cd xdebug-2.0.0beta2 $ sudo -s % source /opt/oss/env.sh % phpize % ./configure --enable-xdebug % make % cp modules/xdebug.so /opt/oss/lib/php
This should install the xdebug.so module inside /opt/oss/lib/php.
Hand edit your php.ini file and add the following line with the correct location of xdebug.so module.
## For Windows, please use the parameter: zend_extension_ts zend_extension="/opt/oss/lib/php/xdebug.so"
For more details on installing Xdebug, please visit their website.
Assuming you have PEAR installed along with PHP 5 and your machine is able to connect to the Internet, just type:
$ pear install XML_Parser
Apart from adding the zend_extenstion line in your php.ini file for Xdebug, you might have to bump up the memory limit for code coverage measurements. Depending on the size of the application, PHPCoverage may require a large amount of memory than generally configured in php.ini, by default. The default 8M limit is almost always not enough. Since coverage measurement is not supposed to happen when the system is being accessed by other users, it is recommended to increase the limit at least to 128MB. It might also be advisable to remove the memory limit by setting the memory_limit parameter to -1 in php.ini file.
PHPCoverage is designed to record how many times a line of PHP code gets executed when instrumentation is enabled. This information is important in validating a test suite that tests the functionality of your application. A good test suite will exercise most lines of code at least once thus giving a fairly high code coverage reading. Code coverage information helps highlight untested code and unused functionality. Code coverage thus provides a metric to measure the completeness of a test suite for an application.
There are different types of code coverage measurements possible such as line coverage, conditional coverage, method (function) coverage, etc. PHPCoverage currently reports only line coverage information. As part of its summary report, it measures and displays the following parameters:
No information is reported on the internet. All reports are generated locally.
After expanding the distribution, go to the 'samples' directory. There are two very basic samples included in this directory (as of release 0.6.2). One is a local code coverage measurement sample and the other is a remote coverage measurement sample. Please see the README files in the respective sample directories for instructions on how to run those samples. These samples include very simple one file applications. You should be able to run and get expected code coverage from both these samples if you have performed all the set up steps correctly. The expected code coverage percentages are given in the respective README files.
First and foremost thing to do when you sense a problem is check the PHP error log. By default the error logging might be turned off in the php.ini file. To enable error logging, change the "log_errors" parameter to "On", and assign a log file path to "error_log" parameter in php.ini file. Make sure that the log file is writable by the user who is running the web server. Restart the web server after this change if you are measuring code coverage remotely. PHPCoverage writes a lot of debug information in the error log and chances are that you will find a hint as to what went wrong. In addition, make sure that you have all the dependencies installed on your system. For remote code coverage measurement, PHPCoverage and its dependencies must be installed on both the client and server machines.
Starting from release 0.6.6, PHPCoverage is dual-licensed under the Open Software License (v2.0) and the GNU Lesser General Public License (v2.1). Users are free to choose the license that best suites their need between these two.
Starting from release 0.6.2, PHPCoverage works on Linux and Windows. The same version should work on both these platforms. There is no separate distribution for Windows. Also, you are encouraged to test it on any other platforms. The goal of PHPCoverage project is to make it a cross-platform tool.
Please visit PHPCoverage tracker page for reporting bugs, feature requests or asking for help.