Tag Archive: PHP Unit

In this part of the series I will cover how to create your first job in Jenkins which will make use of all of the tools installed in the previous two sections of this series.

If you haven’t seen the previous two sections, they can be reached via the links below.

Part 1: Installing the PHP Tools and Jenkins

Part 2: Installing the Plugins and Configuring Jenkins

To begin I will talk about the directories and files you will need to have in your repository for your build to be successful, followed by a discussion of each of those files list, and then then I will cover the creation of your first job.  But, first, I will provide the links to the downloads in this post, up front for convenience.


For convenience, here are all of the downloads covered in this post, so you don’t need to ferret out the links.

  1. Project directory structure and files –> here
  2. Jenkins job template –> here

Directory Structure and Files

Below is the minimal directory structure and files that you will need for the build script to work in Jenkins.  StructureExample is the root folder for the repository (just think of it as the trunk folder in a subversion repository)

Screen Shot 2013-05-15 at 2.57.59 PM

Directory structure and minimal files

From the above image you can see that there are two files “build.xml” and “phpunit.xml” in the root directory.

  • build.xml is an XML file that tells Ant what to do when performing a build.
  • phpunit.xml defines several parameters for PHPUnit to use during its portion of the build.

The location of these files are pretty standard; however, what is not so standard is that I have split the unit tests out into separate directories under the tests directory.  This was done to keep all of the PHP Unit tests separate from the SimpleTest tests.

For convenience you download the above directory structure and files  here.  The download included several versions of build.xml (build.xml.both, build.xml.simpletest, build.xml.phpunit) so you can pick the appropriate version for your build by renaming the appropriate file to build.xml.


The build.xml file is the most important file in the directory; it tells ant what to do during execution.  The file is a little long, roughly 178 lines and created the directory structure shown below.  Since this file is so important I will cover the sections that will be used while performing a build on Jenkins.

Jenkins Build directory


The fist thing to do is to put the name of your project in the file, in the name attribute for this line:

<project name="your-project-name-here" default="build">

Note that the above line also sets the default target to perform “build”. This line;

<target name="build"

This target depends on several other targets to be successful (meaning each of the dependent targets need to complete successfully).

Dependent Targets:

  • prepare –> Ensures that the workspace is setup correctly by wiping out old folders and remaking them.
  • lint –> calls php -l, to perform a syntax check on all of the php files in the directory.
  • phploc –> Uses PHP Loc to determine the number of lines of code in the project.
  • pdepend –> Runs pDepend and creates the dependency reports.
  • phpmd-ci –> Runs PHP Mess Detector to check for code smells and generates some reports of the results.
  • phpcs-ci –> Runs PHP CodeSniffer on the code in the project to check for coding standard violations and generats a report of the results.
  • phpcpd –> Runs PHP Copy Paste Detector which looks for duplicate lines of code.
  • phpdoc –> Generates API documentation using PHP Documentor 2
  • phpunit –> Performs the tests located in tests/phpunit, and uses phpunit.xml for its configuration. After which it creates a report of the results
  • simpletest –> Performs the tests in the TestSuite defined in test/simpletest/TestSuite.php, and then creates a report of the results
  • phpcb –> Creates a browsable report of your code

Target Definitions


The prepare target depends on the clean target, which removes all the directories under the build directory in the workspace. After which, the prepare target re-creates them. ${basedir} contains the path to the current projects (jobs) workspace. For example, if your job was called “example-job” is would contain the path /var/lib/jenkins/jobs/example-job/workspace.

<target name="clean" description="Cleanup build artifacts">
   <delete dir="${basedir}/build/api"/>
   <delete dir="${basedir}/build/code-browser"/>
   <delete dir="${basedir}/build/coverage"/>
   <delete dir="${basedir}/build/logs"/>
   <delete dir="${basedir}/build/pdepend"/>

<target name="prepare" depends="clean" description="Prepare for build">
    <mkdir dir="${basedir}/build/api"/>
    <mkdir dir="${basedir}/build/code-browser"/>
    <mkdir dir="${basedir}/build/coverage"/>
    <mkdir dir="${basedir}/build/logs"/>
    <mkdir dir="${basedir}/build/pdepend"/>


This target uses the php command with the -l parameter to perform a syntax check on the php files in the project. While excluding the tests directory from its check.

<target name="lint" description="Perform syntax check of sourcecode files">
    <apply executable="php" failonerror="true">
        <arg value="-l" />

        <fileset dir="${basedir}">
            <include name="**/*.php" />
            <!-- exclude the tests directory, repeat line below to exclude more -->
            <exclude name="tests/**" />
            <modified />

        <fileset dir="${basedir}/tests">
            <include name="**/*.php" />
            <modified />


This uses PHP Loc to determine the size of the project. The constructed command looks like phploc –exclude ${basedir}/tests –log-csv ${basedir}/build/logs/phploc.csv ${basedir}.
This command tells phploc to look at the code in ${basedir} but exclude the tests directory and to publish the report to build/logs/phploc.csv

<target name="phploc" description="Measure project size using PHPLOC">
    <exec executable="phploc">
        <!-- exclude tests directory -->
        <arg value="--exclude" />
        <arg path="${basedir}/tests" />
        <arg value="--log-csv" />
        <arg value="${basedir}/build/logs/phploc.csv" />
        <arg path="${basedir}" />


This target uses PHP Depend to create several metric reports about your code.

  1. An Overview pyramid covering inheritance, size and complexity, and coupling. You can find information about the pyramid here
  2. An Abstract Instability Chart, which you can find information on here

The target, again ignores the tests directory, as most of the targets do.

<target name="pdepend" description="Calculate software metrics using PHP_Depend">
    <exec executable="pdepend">
        <arg value="--ignore=${basedir}/tests,${basedir}/docs" />
        <arg value="--jdepend-xml=${basedir}/build/logs/jdepend.xml" />
        <arg value="--jdepend-chart=${basedir}/build/pdepend/dependencies.svg" />
        <arg value="--overview-pyramid=${basedir}/build/pdepend/overview-pyramid.svg" />
        <arg path="${basedir}" />


This target uses PHP Mess Detector to check your code for common smells (indicators of possible bad coding or design). There are several rulesets you can use when checking your code: codesize, controversial, design, naming, and unusedcode. You can read about the rulesets here to figure out what each one covers.

You can also define your own rulesets of modify existing rulesets using an xml file. To learn more about there go here and checkout the menu on the right.

The current target configuration tells phpmd to create an xml report, using the codesize ruleset, and place the report in build/logs/pmd.xml. It should examine the current workspace and exclude the test directory.

<target name="phpmd-ci" description="Perform project mess detection using PHPMD creating a log file for the continuous integration server">
    <exec executable="phpmd">
        <arg path="${basedir}" />
        <arg value="xml" />
        <arg value="codesize" />
        <arg value="--reportfile" />
        <arg value="${basedir}/build/logs/pmd.xml" />
        <arg value="--exclude" />
        <arg value="${basedir}/tests" />


This target uses PHP CodeSniffer to check the code in the project, excluding the tests directory, for Zend coding standard violations. The results of the analysis are then put into a checkstyle report in build/logs/checkstyle.xml.

To learn about the available standards and functionality of PHP CodeSniffer, visit here

<target name="phpcs-ci"
        description="Find coding standard violations using PHP_CodeSniffer creating a log file for the continuous integration server">
    <exec executable="phpcs" output="/dev/null">
        <arg value="--report=checkstyle" />
        <arg value="--report-file=${basedir}/build/logs/checkstyle.xml" />
        <arg value="--standard=Zend" />
        <arg value="--ignore=${basedir}/tests" />
        <arg value="--extensions=php" />
        <arg path="${basedir}" />


This target uses PHP Copy Paste Detecter to check for duplicate lines of code in your project, excluding the tests directory, and outputting the results in build/logs/pmd-cpd.xml

<target name="phpcpd" description="Find duplicate code using PHPCPD">
    <exec executable="phpcpd">
        <arg value="--log-pmd" />
        <arg value="${basedir}/build/logs/pmd-cpd.xml" />
        <arg value="--exclude" />
        <arg path="${basedir}/tests" />
        <arg path="${basedir}" />


This target uses PHP Documentor 2 to create API documentation of your code. You can find documentation about using phpdoc here.

<target name="phpdoc" description="Generate API documentation using phpDocumentor 2">
    <exec dir="${basedir}" executable="phpdoc" failonerror="true">
        <!-- excluded directories need the / at the end, else phpdoc ignores it -->
        <arg line="--title='test title' -d . -t build/api -i tests/ " />


This target runs your unit tests using PHP Unit. By default, PHP Unit checks the current directory for a configuration xml file, which is our phpunit.xml file. Because we took this approach, there is not much in the definition of this target.

However, you can find plenty about what you can put in the configuration file here

<target name="phpunit" description="Run unit tests with PHPUnit">
    <exec executable="phpunit" failonerror="true"/>


This target defines how to perform our unit/functionality tests using SimpleTest. You’ll notice that this target definition is a little different than the others. The reason is, is that SimpleTest does not have a nice command line tool that takes parameters like the other tools we are using. To make SimpleTest work, we need to create a little inline bash script.

The one-liner bash script that we will use tells the shell to use php to run TestSuite.php file and then send its output to XML Lint for formatting and output into build/logs/simpletest-results.xml

<!-- Inline bash script to run TestSuite.php and pipe its results to xmllint -->
<!-- XML Lint then outputs the results to simpletest-results.xml -->
<target name="simpletest" description="Run SimpleTest unit tests">
    <exec dir="${basedir}" executable="bash" failonerror="true">
        <arg value="-c"/>
        <arg line='"php tests/simpletest/TestSuite.php | xmllint --format -o build/logs/simpletest-results.xml -"' />


This target uses PHP CodeBrowser to create a browsable interface of your code in your project.

<target name="phpcb" description="Aggregate tool output with PHP_CodeBrowser">
    <exec executable="phpcb">
       <arg value="--log" />
       <arg path="${basedir}/build/logs" />
       <arg value="--ignore" />
       <arg path="${basedir}/tests" />
       <arg value="--source" />
       <arg path="${basedir}" />
       <arg value="--output" />
       <arg path="${basedir}/build/code-browser" />


This file is used to store our configuration for running PHP Unit.

For the over definition, we tell php unit to not backup and restore $GLOBALS or static attributes of user defined classes, to run in strict mode and have verbose output.

For our test suite settings, we set the name (which you should change) and tell php unit to run all of the tests in the php files in tests/phpunit.

Next for our logging settings, we tell PHP Unit to create a coverage report in build/coverage, with the title of your project (don’t forget to set this attribute value) and several other attributes. We also want a coverage-clover report in build/logs/clover.xml and a junit report in build/logs/junit.xml

To learn creating your own PHP Unit configuration file visit here

<?xml version="1.0" encoding="UTF-8"?>

<phpunit backupGlobals="false"

    <testsuite name="Your Test Suit Name Here">
      <directory suffix='.php'>./tests/phpunit</directory>

    <log type="coverage-html" target="build/coverage" title="Your Project Name Here"
         charset="UTF-8" yui="true" highlight="true"
         lowUpperBound="35" highLowerBound="70"/>
    <log type="coverage-clover" target="build/logs/clover.xml"/>
    <log type="junit" target="build/logs/junit.xml" logIncompleteSkipped="false"/>



This file defines out Test Suite for SimpleTest. For our test suite, we define the class MyTests and add the Test Files we want to run using the addFile method. Take note of the use of the magic word __DIR__. This is used so no matter where this file is being invoked from, we won’t have to worry about how the test files are included.

To run the tests in the test suite, a new instance of the class is made and then ran using the JUnitXMLReporter class, so we can jUnit and xUnit compatible output. I had noticed in some other blogs that there was a problem with the header and footer printing in non xml; however, this approach does not have that problem.

 * Include the simpletest file so we can extend TestSuite
require_once 'simpletest/simpletest.php';
 * Include the JUnitXMLReporter class so the output is jUnit and xUnit compatible
require_once 'simpletest/extensions/junit_xml_reporter.php';

class MyTests extends TestSuite
    function __construct()

        //add the files containing the tests we want to perform
        //note the use of __DIR__ so we don't have to worry about file location
        //when running the tests in Jenkins


$test = new MyTests();
$test->run(new JUnitXMLReporter());

Example Test File – TemplateTest.php

I thought it might be pertinent to show an example test file for use with the Test Suite defined above. In the code below, you will notice that I never include simpletest/autorun.php, I only include simpletest/web_tester.php. This is because I want complete control over the running of the tests and their output.

require_once 'simpletest/web_tester.php';

class TemplateTest extends WebTestCase {
    function testLoginPageShowForm() {


This is a simple PHP Unit test file that just does some pushing and popping of an array. In fact, it is the example from chapter 4 “Writing Tests for PHPUnit” from PHP Units web site here

 * Include the PHPUnit Framwork so we can extend the TestCase class
require_once 'PHPUnit/Autoload.php';

class StackTest extends PHPUnit_Framework_TestCase
     * Tests pushing and popping of elements on and off of an array
     * @return Void
    public function testPushAndPop()
        $stack = array();
        $this->assertEquals(0, count($stack));

        array_push($stack, 'foo');
        $this->assertEquals('foo', $stack[count($stack)-1]);
        $this->assertEquals(1, count($stack));

        $this->assertEquals('foo', array_pop($stack));
        $this->assertEquals(0, count($stack));

Setting Up Your First Jenkins Job

This section will cover setting up your first job in jenkins using an existing template. The first thing you will need to do is add the job template to Jenkins.

Adding the job-template To Jenkins

There is a lot of configuration that needs to be done to use all the tools that we’ve installed and referenced in our build.xml file. So, let’s cut out a lot of the work and use an existing job template that has the majority of work done for us already.

  1. Go to the Jenkins job directory
    $cd /var/lib/jenkins/job
  2. Download the job template
    $wget https://googledrive.com/host/0B8dI-j7Xg0phVDRjMnN6QUhfcXc -O job-template.tar.gz
  3. Extract the job template
    $tar xvf job-template.tar.gz
  4. Set the permissions on the directory
    $chown -R jenkins:nogroup job-template/

Setting up the Jenkins Job

  1. Login to Jenkins and click “New Job”
  2. Enter the name of your job

    NOTE: It is a good idea to not have spaces in your job name as it can cause problems

  3. Select “Copy Existing Job”
  4. In the “Copy From” field, type “job-template” (without the quotes)Your screen should look like this

    Jenkins - New Job Screen

  5. Click “OK”
  6. Uncheck “Disable Build”
  7. If you want to use project based security.
    Check “Enable project-based security”You’ll see a permission matrix appear and a field to add a user or group to the matrix

    Jenkins - Project Based Security

    Enter the user or group you want to set the rights for into the “User/group to add” field and click add
    Then set their permissions

    NOTE: Make sure to add yourself or you’ll encounter an issue where your build history disappears until you restart Jenkins

  8. Under the “Source Code Management” section, select “Subversion
  9. Enter the URL to your subversion repository in the “Repository URL” field

    Jenkins - Subversion Settings
    If Jenkins cannot talk to your repository, you may need to enter your credentials.

    1. Click the “enter credentials” link in the error message
    2. Select Username/password authentication
    3. Enter your credentials
    4. Click OK

      Jenkins - Subversion Authentication

  10. Under the “Build Triggers” sectionSelect Poll SCM and use the document linked in the button to determine what you need to enter for your schedule
  11. If you do not want to use PHP Unit or SimpleTest
    Way down under the “Publish xUnit test result report” section, click the delete button for for the unit test suite you don’t want to use.
    PHP Unit

    Jenkins - PHP Unit Settings

    Jenkins - SimpleTest Settings

  12. Click Save
    Note: If you click Apply and then Save, Jenkins throws a parse error
  13. With your job created, you can now perform a build by clicking “Build” on the left side of the screen

As a final note, you will not see many graphs on the main page of a job until you have performed at least two builds.

This is part one of a multi part series where I intend to cover the installation of Jenkins and several PHP tools to use for continuous integration. Along with the configuration of Jenkins and setting up a project and the build xml. This tutorial covers all of these steps in an Ubuntu 12.04 environment.

In this part of the series I will cover installing the following software and tools:

  • Ant
  • Pear
  • PHP 5.4
  • PHP Code Browser
  • PHP Code Coverage
  • PHP Code Sniffer
  • PHP Copy Past Detector
  • PHP Documenter 2
  • PHP Lines of Code
  • PHP Mess Detector
  • PHP Unit
  • Simple Test
  • XML Lint
  • XSL
  • XDebug

Installing PHP 5.4 and Pear

Ubuntu 12.04 by default installs PHP 5.3, so we will need the PPA repository where PHP 5.4 is available from. To do this, we will use the add-apt-repository tool. First we will need to install this tool and then add the repository.

Adding the tool

$apt-get install python-software-properties

Adding the repo

$add-apt-repository ppa:ondrej/php5

Installing PHP 5.4, PHP5.4 dev tools, and pear

$apt-get install php-pear php5-cli php5-common php5 php5-dev

Installing Ant, XSL, XML Lint, and XDebug

Ant will be used to run our build script later.  XSL and XDebug will be used by PHPUnit.  XML Lint will be used to format our reports created by SimpleTest.

To perform the installation of these tools, run the following command.

$apt-get install ant php5-xsl php5-xdebug libxml2-utils

Installing the PHP Tools

Setting up Auto Channel Discovery

$pear config-set auto_discover 1

PHP Code Browser

$pear channel-discover pear.phpqatools.org
$pear install phpqatools/PHP_CodeBrowser
$pear install pear/Text_Highlighter-beta

PHP Code Coverage

$pear install pear.phpunit.de/PHP_CodeCoverage

PHP Code Sniffer

$pear install --alldeps PHP_CodeSniffer

PHP Copy Paste Detecter

PHP-CPD requires the ConsoleTools from ezComponents, so let us take care of that first

$pear channel-discover components.ez.no
$pear install ezc/ConsoleTools

Now we can install PHP-CPD

$pear install --alldeps pear.phpunit.de/phpcpd

PHP Documenter 2

To use the inheritance chart feature, you’ll need to install GraphViz like so (this is not needed, but it’s nice)

$apt-get install graphviz

Now we can install PHP Documenter 2 after discovering its channel

$pear channel-discover pear.phpdoc.org
$pear install --alldeps phpdoc/phpDocumentor-alpha

PHP Lines of Code

$pear install --alldeps pear.phpunit.de/phploc

PHP Mess Detector

To install PHP-MD, we first need to install imagemagick and libmagickwand-dev to take care of the dependencies for imagick.

Installing imagemagick and libmagickwand-dev

$sudo apt-get install imagemagick libmagickwand-dev

Currently the stable version of imagick does not support PHP 5.4, so we need to grab the RC version by doing the following

$pecl config-set preferred_state beta
$pecl install imagick
$pecl config-set preferred_state stable

Now we can install PHP-MD after having pear discover the channels it needs (the auto discover setting didn’t work for this install, so we need to hold pears hand)

$pear channel-discover pear.phpmd.org
$pear channel-discover pear.pdepend.org

$pear install --alldeps phpmd/PHP_PMD

PHP Unit

$pear install --alldeps pear.phpunit.de/PHPUnit

Simple Test

Simple test is an easy to use functional testing library some find easier to use than PHPUnit. To install this library, fist download it like so

$wgetc -c http://sourceforge.net/projects/simpletest/files/simpletest/simpletest_1.1/simpletest_1.1.0.tar.gz

Then move the tar file to the place you want to store the library (I prefer /opt>

$mv simpletest_1.1.0.tar.gz /opt

Uncompress the tar

$cd /opt
$tar xvf simpletest_1.1.0.tar.gz

Both JUnit and xUnit use XML reports to publish test results and SimpleTest does have the ability to output its results in XML, but the format is not compatible with jUnit or xUnit.
To get the output in the format we need, we will need to use the JUnitXMLReporter class. This class is not in the download by default and you will have to download it separately.

Go to the extensions directory

$cd simpletest/extensions

Download the JUnitXMLReporter class

$wget --output-document=junit_xml_reporter.php http://simpletest.svn.sourceforge.net/viewvc/simpletest/simpletest/tags/1.1.0/extensions/junit_xml_reporter.php?revision=2050

Set permissions for the simplest directory

$chown -R jenkins:root /opt/simpletest
$chmod -R 775 /opt/simpletest

Add the library to the include path

$vim /etc/php5/cli/php.ini

Add “:/opt” to the php_include line like so

include_path = ".:/usr/share/php:/opt"

Save the file (escape, :wq, enter)

Installing Jenkins

To install Jenkins we first need to setup OpenJDK 7 as it is recommended over Open JDK 6, which Ubuntu will try to install.

Installing OpenJDK 7

Installing OpenJDK7 JDK

$apt-get install openjdk7-jdk

The install will not setup the $JAVA_HOME environment variable, so let’s take care of that.

Edit /etc/environment

Add the following line


Note: If your install is not a 64-bit install your path will be different, please check /usr/lib/jvm to determine your proper path

Not that java is installed and the $JAVA_HOME variable has been defined, please exit (exit sudo or logout) and restart your terminal session (re login or enter sudo again)

Installing Jenkins

To perform the install, we first need to tell apt-get to get the latest versions from jenkins-ci.org

Run the following command to the key for jenkins-ci.org’s repo

wget -q -O - http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key | sudo apt-key add -

Add the repo to apt-gets’ sources

sh -c 'echo deb http://pkg.jenkins-ci.org/debian binary/ > /etc/apt/sources.list.d/jenkins.list'

Update apt-get

apt-get update

Install Jenkins

$apt-get install jenkins

In The Next Part…

In the next part of the series I will cover installing the plugins we will use in Jenkins, configuring Jenkins to use SSL, and configuring Jenkins to authenticate to Active Directory