VisualPHPUnit is a visual front-end for PHPUnit. It offers the following features:
- A stunning front-end which organizes test and suite results
- The ability to view unit testing progress via graphs
- An option to maintain a history of unit test results through the use of snapshots
- Enumeration of PHPUnit statistics and messages
- Convenient display of any debug messages written within unit tests
- Sandboxing of PHP errors
- The ability to generate test results from both a browser and the command line
VisualPHPUnit requires PHP 5.3+ and PHPUnit v3.5+.
VPU underwent a complete rewrite in v2.0. Users who are looking to upgrade from v1.x are encouraged to follow the installation instructions outlined below.
Because the UI has been changed, snapshots from v1.x will not render correctly in v2.x.
Test statistics generated in v1.x, however, can still be used. When installing, ignore the migration and run the following commands against your old VPU database instead:
alter table SuiteResult change success succeeded int(11) not null;
alter table TestResult change success succeeded int(11) not null;
While no longer actively supported, v1.x can be found on its own branch.
- Download and extract (or git clone) the project to a web-accessible directory.
- Change the permissions of
app/resource/cache
to777
. - Open
app/config/bootstrap.php
with your favorite editor.- Within the
$config
array, changepear_path
so that it points to the directory where PEAR is located. - Within the
$config
array, changetest_directory
so that it points to the root directory where your unit tests are stored.
- Within the
Place this code block within the http {}
block in your nginx.conf
file:
server {
server_name vpu;
root /srv/http/vpu/app/public;
index index.php;
access_log /var/log/nginx/vpu_access.log;
error_log /var/log/nginx/vpu_error.log;
location / {
try_files $uri /index.php;
}
location ~ \.php$ {
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
Note that you will have to change the server_name
to the name you use in your hosts file. You will also have to adjust the directories according to where you installed the code. In this configuration, /srv/http/vpu/ is the project root. The public-facing part of VisualPHPUnit, however, is located in app/public within the project root (so in this example, it's /srv/http/vpu/app/public).
When that's done, restart your web server, and then point your browser at the server name you chose above!
VPU comes with .htaccess files, so you won't have to worry about configuring anything. Simply point your browser at the location where you installed the code!
VPU comes with many of its features disabled by default. In order to take advantage of them, you'll have to modify a few more lines in app/config/bootstrap.php
.
If you'd like to enable graph generation, you will have to do the following:
- Within the
$config
array, changestore_statistics
totrue
. If you'd like, you can keep this set asfalse
, though you will have to change the 'Store Statistics' option to 'Yes' on the UI if you want the test statistics to be used in graph generation. - Run the migration
app/resource/migration/01_CreateSchema.sql
against a MySQL database.- Note that this will automatically create a database named
vpu
with the tables needed to save your test statistics.
- Note that this will automatically create a database named
- Within the
$config
array, change the settings within thedb
array to reflect your database settings.- Note that if you're using the migration described above,
database
should remain set tovpu
. - The
plugin
directive should not be changed.
- Note that if you're using the migration described above,
If you'd like to enable snapshots, you will have to do the following:
- Within the
$config
array, changecreate_snapshots
totrue
. If you'd like, you can keep this set asfalse
, though you will have to change the 'Create Snapshots' option to 'Yes' on the UI if you want the test results to be saved. - Within the
$config
array, changesnapshot_directory
to a directory where you would like the snapshots to be saved.- Note that this directory must have the appropriate permissions in order to allow PHP to write to it.
- Note that the dropdown list on the 'Archives' page will only display the files found within
snapshot_directory
.
If you'd like to enable error sandboxing, you will have to do the following:
- Within the
$config
array, changesandbox_errors
totrue
. If you'd like, you can keep this set asfalse
, though you will have to change the 'Sandbox Errors' option to 'Yes' on the UI if you want the errors encountered during the test run to be sandboxed. - Within the
$config
array, changeerror_reporting
to reflect which errors you'd like to have sandboxed. See PHP's manual entry on error_reporting for more information.
Ignore Hidden Folders
By default, the file selector does not display hidden folders (i.e., folders with a '.' prefix). If you'd like to display hidden folders, you will have to do the following:
- Within the
$config
array, changeignore_hidden_folders
tofalse
.
If you'd like to use a PHPUnit XML configuration file to define which tests to run, you will have to do the following:
- Within the
$config
array, changexml_configuration_file
to the path where the configuration file can be found.- Note that if you leave this set to
false
, but select 'Yes' for the 'Use XML Config' option on the UI, VPU will complain and run with the tests chosen in the file selector instead.
- Note that if you leave this set to
- Modify your PHPUnit XML configuration file to include this block:
<!-- This is required for VPU to work correctly -->
<listeners>
<listener class="PHPUnit_Util_Log_JSON"></listener>
</listeners>
If you'd like to load any bootstraps, you will have to do the following:
- Within the
$config
array, list the paths to each of the bootstraps within thebootstraps
array.
t - Run Tests
VPU can be run at the command line, making it possible to automate the generation of test results via cron.
The CLI script requires that the xml_configuration_file
setting within the $config
array of app/config/bootstrap.php
be properly set. VPU will run the tests specified in the XML configuration file. Please be sure that the configuration file contains the required JSON listener.
In order to save the test results, the CLI script also requires that the snapshot_directory
setting within the $config
array of app/config/bootstrap.php
be properly set. Note that the value of create_snapshots
within the $config
array has no effect on the CLI script.
Errors will be sandboxed if sandbox_errors
is set to true
within the $config
array of app/config/bootstrap.php
.
Test statistics will be stored if store_statistics
is set to true
within the $config
array of app/config/bootstrap.php
. Make sure that the database is configured correctly.
VPU can be executed from the command line using the following command:
# from the project root
bin/vpu
Current stable release is v2.1, last updated on August 19, 2012.
Feel free to send any feedback you may have regarding this project to [email protected].
Special thanks to Matt Mueller (http://mattmueller.me/blog/), who came up with the initial concept, wrote the original code (https://github.com/MatthewMueller/PHPUnit-Test-Report), and was kind enough to share it.
Thanks to Mike Zhou, Hang Dao, Thomas Ingham, and Fredrik Wollsén for their suggestions!