Finally, PHPUnderControl for Drupal 6 and 7.

[First draft]

[Update: Due to a latest code change in Drupal7's simpletest module, Drupal 7 support is now broken :-( ]

Last year (2008) I created a patch for PHPUnderControl. This patch allowed one to run Drupal unit tests from inside PHPUnderControl. That patch was meant for Drupal 5. Since then a lot has changed - Drupal 6 was released, CruiseControl got an upgrade, and Barack Obama became the president. Almost every new Drupal project now uses Drupal 6. To my surprise, the SimpleTest module is now part of Drupal core (starting from Drupal 7). To keep pace with all these changes, I have also updated my patch.

Before taking you to the patch, I have something to say about the changes the SimpleTest module has gone through in the recent past. SimpleTest is the name of a PHP unit testing framework written by Marcus Baker and hosted at simpletest.sourceforge.net (and also at simpletest.org). The Drupal SimpleTest module adopts this framework to provide a unit testing framework for Drupal. This is how the SimpleTest module has worked in Drupal 5 and Drupal 6. But later the module was accepted as a Drupal core module. So the SimpleTest module will be shipped with Drupal 7 onwards. But when the module went into Drupal 7, it abandoned the original SimpleTest framework (simpletest.sourceforge.net) and implemented the funtionality on its own. This means that Drupal 7 users will not have to download the original SimpleTest framework from Sourceforge.net. Soon after, the SimpleTest module from Drupal 7 was backported to Drupal 6. Now we have two SimpleTest modules for Drupal 6 - the one that relies on the original framework and the one that does not. This can be slightly confusing. The following diagram might help to reduce the confusion -

The main point to take from this diagram is - there are two completely different SimpleTest modules for Drupal 6 and these are denoted by branch names 6.X-1.X and 6.X-2.X. Because 6.X-1.X relies on the SimpleTest framework, my Drupal 5 patches works fine with it. As for 6.X-2.X, there's no patch. So unit tests written for the 6.X-2.X branch will not work with my patches. My apologies. But I do have a different patch for Drupal 7's SimpleTest module. From this point, I'll refer to the 6.X-1.X branch everytime I'll speak of SimpleTest for Drupal 6.

Although PHPUnderControl was written for CruiseControl 2.7.3 and PHPUnderControl has not been updated for CruiseControl 2.8.2, when I tried PHPUnderControl with CruiseControl 2.8.2, it worked without any hickup. That was a big relief for me as a failure had the potential to spoil the whole party.

PHPUnderControl can display report from PHPCodeSniffer which is a coding convention monitor. During the upgrade work for the patch, I created a sniff for PHPCodeSniffer that follows the Drupal coding standard. This Sniff is in alpha stage, but I am making it available too.

So how do we use the patch for Drupal 6 (or 7)? Here are the steps :-

[I am assuming that we are doing everything inside the Unix home directory "testenv" whose absolute path is "/home/testenv". You are, of course, free to use a different path.]

0. Download and uncompress CruiseControl. I am assuming CruiseControl now resides at "/home/testenv/cc".

1. Install PHPUnderControl.

2. Copy the patch into the "/home/testenv/cc/webapps/cruisecontrol/" directory.

3. Create these three directories - "/home/testenv/cc/projects/PROJECT_NAME/build", "/home/testenv/cc/projects/PROJECT_NAME/build/logs" and ""/home/testenv/cc/projects/PROJECT_NAME/build/src-doc". Don't forget to replace "PROJECT_NAME" with the actual name of the project.

4. Checkout a copy of your Drupal project into "/home/testenv/cc/projects/PROJECT_NAME/source" and then install the Drupal instance. A good alternative is to create a symbolic link to an existing Drupal installation.

5. Once Drupal is installed (or symlinked), make sure that the SimpleTest module is enabled.

6. Now include the Drupal project in CruiseControl's main configuration file (i.e. config.xml). Here is an example file.

7. The last step is to create the build file (build.xml, the famous Ant build file) for the project. This build file will decide what will happen everytime any new code is committed into the version control system. In our case, this build file will do. Please note the paths inside this build file. These must be changed to suit your system.

The following tables lists the rest of the downloads:-

The sample build.xml file assumes that the unit test running script is at "/home/testenv/run-tests-xml.php". It also assumes that the Drupal Sniff is at "/home/testenv/DrupalSniff". Also important is the path of the PHPDoc template. The sample file looks for the template at "/usr/local/share/pear/data/phpUnderControl/data/phpdoc". The build file also uses the URL of the Drupal install (http://localhost/drupal). Please update these as needed.

Once the build file is prepared, test it manually from inside the project directory -
$ ../../apache-ant-1.7.0/bin/ant
Or $ ../../apache-ant-1.7.0/bin/ant test (This runs the unit tests only)
Or $ ../../apache-ant-1.7.0/bin/ant codesniffer (This runs the code sniffer only)
Or $ ../../apache-ant-1.7.0/bin/ant doc (This generates source code docs only)

If everythings goes fine, then congratulate yourself and fire up cruisecontrol:
[~/cc] $ ./cruisecontrol.sh

Next browse to "http://localhost:8080/cruisecontrol/index". The Drupal project should be listed.

I am currently running PHPUnderControl on Drupal head (AKA Drupal 7) at "http://remoteguru.info:4040/cruisecontrol/buildresults/drupal-head". Here a build is triggered everytime anybody commits code into the code repository of the Drupal core at "cvs.drupal.org/cvs/drupal/". This might give you a good demo of how the final product will look like.

Here I must link to the excellent PHPUnderControl installation instructions. If you are looking for some background information on CruiseControl, PHPUnderControl and SimpleTest, then please have a look at another article from this very site.