Sebastian Bergmann - PHPUnit

GTAC 2010

nospam@example.com (Sebastian Bergmann) — Fri, 23 Jul 2010 15:20:35 +0200

I have been invited to attend the 5th Annual Google Test Automation Conference, better known as GTAC, in Hyderabad, India in October. I am very much looking forward to discuss cutting edge challenges in test automation and evaluate potential solutions, especially with this year's focus on testability.

Another thing I like about this year's GTAC is that the participants are responsible for selecting the presentations for the conference. Here is my submission:

Challenges in Unit Testing PHP Applications

According to TIOBE, PHP is the most popular programming language after C/C++ and Java. The language has made strong inroads into large-scale, business-critical Web systems. In the six years since the release of PHP 5 -- which not only kickstarted the development of PHP-based frameworks for Web development but also the development of tools for dynamic and static testing techniques -- the PHP community as a whole has developed an increasing interest in developing software that delivers the best possible quality.

When PHP developers start to write unit tests they rarely find themselves without any constraints that are imposed by prior work of less than optimal quality. It is a well-known fact that writing unit tests for legacy code is hard. In the case of PHP it can be even harder: the legacy code has not only been written without testability in mind, but it may have been written for earlier versions of PHP that encouraged practices that make the code next to impossible to unit test.

PHPUnit, the de-facto standard framework for unit-testing PHP code, has some unique features not found in other xUnit test frameworks that allow the testing of untestable code. While developers should not use these features (as they are not required when writing tests for testable code), these features ease the pain of writing tests for legacy code and thus help developers get started with unit testing before they refactor the code for testability.

This session, presented by the creator of PHPUnit, highlights the challenges developers are facing when unit testing legacy PHP code. Some of these challenges will be familiar to developers that use other programming languages such as Java but they will see a new perspective on the problem and different approaches to solve it.

Although I am hoping, of course, that my submission will be accepted by my peers, I know that GTAC will be valuable for me even if I do not get to present: the "hallway track" of GTAC 2008 was amazing.

PHPUnit 3.5: Refactoring to Components

nospam@example.com (Sebastian Bergmann) — Fri, 23 Jul 2010 14:00:00 +0200

When you look at the list of changes for PHPUnit 3.5, you will see that many of them deal with refactoring to components. Here is an overview of these new components:

PHP_CodeCoverage
The collection, processing, and rendering of code coverage information has been factored out into a separate component. A bit more information can be found here.
PHPUnit_MockObject
The functionality to automatically generate an object that can act as a test double for a specified original class has been factored out into a separate component. Do not worry, getMock() and related methods will work just as they did in previous versions of PHPUnit. The refactoring, however, makes the usage of other mock object libraries (such as Mockery or Phake, for instance) easier.
DbUnit
The database testing functionality that is provided by the DbUnit extension and the respective DatabaseTestCase class has been moved to a separate component. Michael Lively Jr, the author of DbUnit, is now able to make releases of the database testing extension on a release schedule that is separate from PHPUnit itself, meaning that I will be even less involved in its development than I have before.
PHPUnit_Selenium
SeleniumTestCase, the Selenium RC integration for PHPUnit, has been moved to a separate component to allow a release cycle separate from PHPUnit itself.
File_Iterator, PHP_Timer, Text_Template
Utility methods to collect files and report resource usage as well as a simple templating mechanism have been moved to separate components so that they can be reused by other tools such as phpcb, phpcs, phpcpd, and pdepend.

PHPUnit 3.5 Beta 1

nospam@example.com (Sebastian Bergmann) — Tue, 08 Jun 2010 10:20:00 +0200

To celebrate the 15th birthday of PHP, I have released PHPUnit 3.5 Beta 1 today. The refactoring towards components is a "new feature" that is already visible upon installation:

sb@vmware ~ % pear install phpunit/PHPUnit-beta
phpunit/PHPUnit can optionally use PHP extension "dbus"
downloading PHPUnit-3.5.0beta1.tgz ...
Starting to download PHPUnit-3.5.0beta1.tgz (105,588 bytes)
........................done: 105,588 bytes
downloading DbUnit-1.0.0beta1.tgz ...
Starting to download DbUnit-1.0.0beta1.tgz (38,209 bytes)
...done: 38,209 bytes
downloading File_Iterator-1.2.1.tgz ...
Starting to download File_Iterator-1.2.1.tgz (3,225 bytes)
...done: 3,225 bytes
downloading Text_Template-1.0.0.tgz ...
Starting to download Text_Template-1.0.0.tgz (2,493 bytes)
...done: 2,493 bytes
downloading PHP_CodeCoverage-1.0.0beta1.tgz ...
Starting to download PHP_CodeCoverage-1.0.0beta1.tgz (108,640 bytes)
...done: 108,640 bytes
downloading PHP_Timer-1.0.0.tgz ...
Starting to download PHP_Timer-1.0.0.tgz (2,536 bytes)
...done: 2,536 bytes
downloading PHPUnit_MockObject-1.0.0beta1.tgz ...
Starting to download PHPUnit_MockObject-1.0.0beta1.tgz (15,816 bytes)
...done: 15,816 bytes
downloading PHPUnit_Selenium-1.0.0beta1.tgz ...
Starting to download PHPUnit_Selenium-1.0.0beta1.tgz (15,298 bytes)
...done: 15,298 bytes
downloading PHP_TokenStream-1.0.0beta1.tgz ...
Starting to download PHP_TokenStream-1.0.0beta1.tgz (7,023 bytes)
...done: 7,023 bytes
install ok: channel://pear.phpunit.de/File_Iterator-1.2.1
install ok: channel://pear.phpunit.de/Text_Template-1.0.0
install ok: channel://pear.phpunit.de/PHP_Timer-1.0.0
install ok: channel://pear.phpunit.de/PHP_TokenStream-1.0.0beta1
install ok: channel://pear.phpunit.de/PHP_CodeCoverage-1.0.0beta1
install ok: channel://pear.phpunit.de/PHPUnit-3.5.0beta1
install ok: channel://pear.phpunit.de/DbUnit-1.0.0beta1
install ok: channel://pear.phpunit.de/PHPUnit_MockObject-1.0.0beta1
install ok: channel://pear.phpunit.de/PHPUnit_Selenium-1.0.0beta1

Happy Birthday PHP! And have fun testing (with) PHPUnit 3.5!

Using PHPUnit from a Git Checkout

nospam@example.com (Sebastian Bergmann) — Thu, 15 Apr 2010 13:35:00 +0200

Users of PHPUnit frequently ask me questions such as "How do I use PHPUnit from a Git checkout?" or "How do I run PHPUnit's own test suite?" This article provides the answers to these questions.

Getting PHPUnit from Git

sb@thinkpad ~ % git clone git://github.com/sebastianbergmann/phpunit.git

You now have a phpunit directory in your current working directory that contains the branch for PHPUnit 3.5 (at the time of writing) because the 3.5 branch is currently configured as the default branch for the PHPUnit repository on GitHub. If you want to switch to the branch for PHPUnit 3.4, for instance, you can use

sb@thinkpad phpunit % git checkout -b 3.4 origin/3.4

This tells Git to create a new local branch of name 3.4 (-b 3.4) that is set up to track the remote branch 3.4 from origin (origin/3.4). Git automatically switches to the newly created local branch. Using

sb@thinkpad phpunit % git checkout 3.5

you can switch back to the branch for PHPUnit 3.5.

Running PHPUnit from a Git checkout

Inside the phpunit directory you will find the phpunit.php script. Using this script you can invoke the PHPUnit TextUI test runner:

sb@thinkpad ~ % phpunit/phpunit.php
PHPUnit @package_version@ by Sebastian Bergmann.
.
.
.

The @package_version@ placeholder string for the version information makes it clear that a non-release version of PHPUnit is being used. Upon installation, the PEAR Installer replaces this placeholder string with the relevant information.

Running PHPUnit's Own Test Suite

Running PHPUnit's own test suite is as easy as invoking phpunit in the checkout directory:

sb@thinkpad phpunit % phpunit                  
PHPUnit @package_version@ by Sebastian Bergmann.

............................................................  60 / 681
............................................................ 120 / 681
............................................................ 180 / 681
............................................................ 240 / 681
............................................................ 300 / 681
............................................................ 360 / 681
............................................................ 420 / 681
............................................................ 480 / 681
................................SSSSSSSSSSSSSSSSSSSSSSSSSSSS 540 / 681
SSSS.......................................S................ 600 / 681
............................................................ 660 / 681
.....................

Time: 27 seconds, Memory: 56.25Mb

OK, but incomplete or skipped tests!
Tests: 681, Assertions: 1459, Skipped: 33.

Writing code coverage data to XML file, this may take a moment.

Generating code coverage report, this may take a moment.

The above works because there is an XML configuration for PHPUnit (phpunit.xml.dist) in the directory that contains information about which tests to run and what logfiles to produce.

Code Coverage Dashboard

nospam@example.com (Sebastian Bergmann) — Sat, 03 Apr 2010 19:15:00 +0200

Almost a year ago I started to factor out all the code that deals with code coverage in PHPUnit and put it into a separate component. The name of this component is PHP_CodeCoverage.

PHP_CodeCoverage is a library that provides collection, processing, and rendering functionality for PHP code coverage information. Its architecture has support for multiple backends for collecting code coverage information (currently only support for Xdebug is implemented) and for reporting code coverage information (for instance using Clover XML or as an HTML report).

As mentioned earlier, the HTML report that is generated by PHP_CodeCoverage shows the CRAP Index software metric for each function or method. Today I built on this earlier development and added a "dashboard view" to the HTML report that shows the following software metrics:

Class Coverage Distribution: This is a bar chart that shows how many classes have 0%, ..., 100% code coverage
Class Complexity: This is a scatter chart that shows the coverage (X axis) and the complexity (Y axis) of the classes
Top Project Risks: This is list of the classes with the highest CRAP Index
Least Tested Methods: This is the list of the least tested methods

You can see an example of the dashboard view below:

Stubbing Hard-Coded Dependencies

nospam@example.com (Sebastian Bergmann) — Tue, 16 Feb 2010 08:00:00 +0100

This article is part of a series on testing untestable code:

In a unit test, mock objects can simulate the behavior of complex, real (non-mock) objects and are therefore useful when a real object is difficult or impossible to incorporate into a unit test.

A mock object can be used anywhere in the program where the program expects an object of the mocked class. However, this only works as long as the object can be passed into the context where the original object is used.

Consider the following example:

<?php
require_once 'Bar.php';
 
class Foo
{
    public function doSomething()
    {
        // ...
 
        $bar = new Bar;
        $bar->doSomethingElse();
 
        // ...
 
        return TRUE;
    }
}
?>

<?php
class Bar
{
    public function doSomethingElse()
    {
        print '*';
    }
}
?>

With the code above, it is impossible to run a unit test for the Foo::doSomething() method without also creating an object of Bar. As the method creates the object of Bar itself, we cannot inject a mock object in its stead.

In a perfect world, code such as the above could be refactored using Dependency Injection:

<?php
require_once 'Bar.php';
 
class Foo
{
    public function doSomething(Bar $bar = NULL)
    {
        if ($bar === NULL) {
            $bar = new Bar;
        }
 
        // ...
 
        $bar->doSomethingElse();
 
        // ...
 
        return TRUE;
    }
}
?>

Unfortunately, this is not always possible (not because of technical reasons, though).

This is where the set_new_overload() function that is provided by the test_helpers extension for the PHP Interpreter comes into play. It can be used to register a callback that is automatically invoked when the new operator is executed:

<?php
require_once 'Foo.php';
 
class FooTest extends PHPUnit_Framework_TestCase
{
    protected function setUp()
    {
        $this->getMock(
          'Bar',                    /* name of class to mock     */
          array('doSomethingElse'), /* list of methods to mock   */
          array(),                  /* constructor arguments     */
          'BarMock'                 /* name for mocked class     */
        );
 
        set_new_overload(array($this, 'newCallback'));
    }
 
    protected function tearDown()
    {
        unset_new_overload();
    }
 
    protected function newCallback($className)
    {
        switch ($className) {
            case 'Bar': return 'BarMock';
            default:    return $className;
        }
    }
 
    public function testDoSomething()
    {
        $foo = new Foo;
        $this->assertTrue($foo->doSomething());
    }
}
?>

Lets run this unit test:

PHPUnit 3.4.10 by Sebastian Bergmann.

.

Time: 0 seconds, Memory: 7.50Mb

OK (1 test, 2 assertions)

Note that there is no * (printed from Bar::doSomethingElse()) in the output above.

Sharing Fixture Between Tests

nospam@example.com (Sebastian Bergmann) — Sun, 14 Feb 2010 10:40:10 +0100

There are few good reasons to share fixtures between tests, but in most cases the need to share a fixture between tests stems from an unresolved design problem.

A good example of a fixture that makes sense to share across several tests is a database connection: you log into the database once and reuse the database connection instead of creating a new connection for each test. This makes your tests run faster.

PHPUnit 3.5 removes the fixture sharing feature of the TestSuite class. It was tedious to use this feature as it required the usage of a custom TestSuite class in addition to the test case class. Furthermore, its implementation was a "hack".

PHPUnit 3.4 introduced the setUpBeforeClass() and tearDownAfterClass() template methods that can be used in a test case class. These methods allow a much cleaner and simpler implementation of fixture sharing between tests of the same test case class:

<?php
class DatabaseTest extends PHPUnit_Framework_TestCase
{
    protected static $dbh;
 
    public static function setUpBeforeClass()
    {
        self::$dbh = new PDO('sqlite::memory:');
    }
 
    public static function tearDownAfterClass()
    {
        self::$dbh = NULL;
    }
}
?>

The example above uses the setUpBeforeClass() and tearDownAfterClass() template methods to connect to the database before the test case class' first test and to disconnect from the database after the last test of the test case, respectively.

It cannot be emphasized enough that sharing fixtures between tests reduces the value of the tests. The underlying design problem is that objects are not loosely coupled. You will achieve better results solving the underlying design problem and then writing tests using test doubles, than by creating dependencies between tests at runtime and ignoring the opportunity to improve your design.

Stubbing and Mocking Static Methods

nospam@example.com (Sebastian Bergmann) — Fri, 12 Feb 2010 06:30:00 +0100

This article is part of a series on testing untestable code:

With PHPUnit 3.5 it will be possible to stub and mock static methods.

Consider the class Foo:

<?php
class Foo
{
    public static function doSomething()
    {
        return static::helper();
    }
 
    public static function helper()
    {
        return 'foo';
    }
}
?>

When testing Foo::doSomething() we want to decouple it from its dependency Foo::helper(). With PHPUnit 3.5 and PHP 5.3 as well as consistent use of late static binding (using static:: instead of self::) the following is possible:

<?php
class FooTest extends PHPUnit_Framework_TestCase
{
    public function testDoSomething()
    {
        $class = $this->getMockClass(
          'Foo',          /* name of class to mock     */
          array('helper') /* list of methods to mock   */
        );
 
        $class::staticExpects($this->any())
              ->method('helper')
              ->will($this->returnValue('bar'));
 
        $this->assertEquals(
          'bar',
          $class::doSomething()
        );
    }
}
?>

The new staticExpects() method works similar to the non-static expects() variant.

This approach only works for the stubbing and mocking of static method calls where caller and callee are in the same class. This is because static methods are death to testability:

"Unit-Testing needs seams, seams is where we prevent the execution of normal code path and is how we achieve isolation of the class under test. Seams work through polymorphism, we override/implement class/interface and then wire the class under test differently in order to take control of the execution flow. With static methods there is nothing to override. Yes, static methods are easy to call, but if the static method calls another static method there is no way to override the called method dependency."

Testing Code That Uses Singletons

nospam@example.com (Sebastian Bergmann) — Thu, 11 Feb 2010 15:45:00 +0100

This article is part of a series on testing untestable code:

I frequently quote Miko Hevery with

"It is hard to test code that uses singletons."

And then my audience asks me ...

Why is it hard to test code that uses singletons?

Lets have a look at the default implementation of the Singleton design pattern in PHP:

<?php
class Singleton
{
    private static $uniqueInstance = NULL;
 
    protected function __construct() {}
    private final function __clone() {}
 
    public static function getInstance()
    {
        if (self::$uniqueInstance === NULL) {
            self::$uniqueInstance = new Singleton;
        }
 
        return self::$uniqueInstance;
    }
}
?>

The code above declares a class that cannot be instantiated (or cloned) by a client using the new (or clone) operator(s). To get a reference to the only instance of the class one has to use the static method getInstance(). Usually the code that uses the Singleton (which we will refer to as client) is strongly coupled to the getInstance() method:

<?php
class Client
{
    public function doSomething()
    {
        $singleton = Singleton::getInstance();
 
        // ...
    }
}
?>

It is impossible to write a test for the doSomething() method without also invoking the singleton's getInstance() method. This means that we cannot get a fresh instance of the Singleton class and thus have no guarantee that there are no side effects in multiple tests that interact with the singleton.

Dependency Injection

Dependency Injection can help with decoupling the client from the getInstance() method:

<?php
class Client
{
    public function doSomething(Singleton $singleton = NULL)
    {
        if ($singleton === NULL) {
            $singleton = Singleton::getInstance();
        }
 
        // ...
    }
}
?>

Instead of unconditionally invoking the getInstance() method inside the doSomething() we can now optionally pass in an instance of the Singleton class. This allows us to pass in a test-specific equivalent such as a mock object or stub:

<?php
class ClientTest extends PHPUnit_Framework_TestCase
{
    public function testSingleton()
    {
        $singleton = $this->getMock(
          'Singleton', /* name of class to mock     */
          array(),     /* list of methods to mock   */
          array(),     /* constructor arguments     */
          '',          /* name for mocked class     */
          FALSE        /* do not invoke constructor */
        );
 
        // ... configure $singleton ...
 
        $client = new Client;
        $client->doSomething($singleton);
 
        // ...
    }
}
?>

Alternative Singleton Implementations

Either as an alternative or in addition to rewriting the clients to optionally accept an instance of the Singleton class as an argument, we can also rewrite the Singleton class to make testing easier.

Resettable Singleton

The first approach is to add a reset() method to the Singleton class:

<?php
class Singleton
{
    private static $uniqueInstance = NULL;
 
    protected function __construct() {}
    private final function __clone() {}
 
    public static function getInstance()
    {
        if (self::$uniqueInstance === NULL) {
            self::$uniqueInstance = new Singleton;
        }
 
        return self::$uniqueInstance;
    }
 
    public static function reset() {
        self::$uniqueInstance = NULL;
    }
}
?>

Invoking the reset() method causes the getInstance() method to create a fresh object of the Singleton class the next time it is called.

Singleton with Test Context

The second approach is to add a testing context to the Singleton class:

<?php
class Singleton
{
    private static $uniqueInstance = NULL;
    public static $testing = FALSE;
 
    protected function __construct() {}
    private final function __clone() {}
 
    public static function getInstance()
    {
        if (self::$uniqueInstance === NULL ||
            self::$testing) {
            self::$uniqueInstance = new Singleton;
        }
 
        return self::$uniqueInstance;
    }
}
?>

Setting Singleton::$testing = TRUE; causes the getInstance() method to create a fresh object of the Singleton class each time it is called.

PHPUnit Can Help, Too

PHPUnit has a backup/restore mechanism for static attributes of classes.

This is yet another feature of PHPUnit that makes the testing of code that uses global state (which includes, but is not limited to, global and superglobal variables as well as static attributes of classes) easier.

Just Because You Can, Does Not Mean You Should

Yes, it is possible write testable code that uses singletons.
This does not mean, however, that you should use them without thinking twice.

Testing Your Privates

nospam@example.com (Sebastian Bergmann) — Tue, 09 Feb 2010 13:00:59 +0100

This article is part of a series on testing untestable code:

No, not those privates. If you need help with those, this book might help.

One question I get over and over again when talking about Unit Testing is this:

"How do I test the private attributes and methods of my objects?"

Lets assume we have a class Foo:

<?php
class Foo
{
    private $bar = 'baz';
 
    public function doSomething()
    {
        return $this->bar = $this->doSomethingPrivate();
    }
 
    private function doSomethingPrivate()
    {
        return 'blah';
    }
}
?>

Before we explore how protected and private attributes and methods can be tested directly, lets have a look at how they can be tested indirectly.

The following test calls the testDoSomething() method which in turn calls the doSomethingPrivate() method:

<?php
class FooTest extends PHPUnit_Framework_TestCase
{
    /**
     * @covers Foo::doSomething
     * @covers Foo::doSomethingPrivate
     */
    public function testDoSomething()
    {
        $foo = new Foo;
        $this->assertEquals('blah', $foo->doSomething());
    }
}
?>

The test above assumes that testDoSomething() only works correctly when testDoSomethingPrivate() works correctly. This means that we have indirectly tested testDoSomethingPrivate(). The problem with this approach is that when the test fails we do not know directly where the root cause for the failure is. It could be in either testDoSomething() or testDoSomethingPrivate(). This makes the test less valuable.

PHPUnit supports reading protected and private attributes through the PHPUnit_Framework_Assert::readAttribute() method. Convenience wrappers such as PHPUnit_Framework_TestCase::assertAttributeEquals() exist to express assertions on protected and private attributes:

<?php
class FooTest extends PHPUnit_Framework_TestCase
{
    public function testPrivateAttribute()
    {
        $this->assertAttributeEquals(
          'baz',  /* expected value */
          'bar',  /* attribute name */
          new Foo /* object         */
        );
    }
}
?>

PHP 5.3.2 introduces the ReflectionMethod::setAccessible() method to allow the invocation of protected and private methods through the Reflection API:

<?php
class FooTest extends PHPUnit_Framework_TestCase
{
    /**
     * @covers Foo::doSomethingPrivate
     */
    public function testPrivateMethod()
    {
        $method = new ReflectionMethod(
          'Foo', 'doSomethingPrivate'
        );
 
        $method->setAccessible(TRUE);
 
        $this->assertEquals(
          'blah', $method->invoke(new Foo)
        );
    }
}
?>

In the test above we directly test testDoSomethingPrivate(). When it fails we immediately know where to look for the root cause.

I agree with Dave Thomas and Andy Hunt, who write in their book "Pragmatic Unit Testing":

"In general, you don't want to break any encapsulation for the sake of testing (or as Mom used to say, "don't expose your privates!"). Most of the time, you should be able to test a class by exercising its public methods. If there is significant functionality that is hidden behind private or protected access, that might be a warning sign that there's another class in there struggling to get out."

So: Just because the testing of protected and private attributes and methods is possible does not mean that this is a "good thing".

CRAP in PHPUnit 3.5

nospam@example.com (Sebastian Bergmann) — Tue, 12 Jan 2010 10:30:00 +0100

For the upcoming PHPUnit 3.5, I have factored out all code that is related to code coverage and put it into a separate component: PHP_CodeCoverage.

PHP_CodeCoverage is a component that provides collection, processing, and rendering functionality for PHP code coverage information. It makes PHPUnit's mature code coverage functionality available outside of PHPUnit.

Having all code that deals with code coverage in a separate component allows for easier development and better testing. The first result of these improved development conditions is a small new feature that I recently implemented, the support for the CRAP metric.

From crap4j.org:

The CRAP (Change Risk Analysis and Predictions) software metric [has] a mildly offensive metric name [and helps] to help protect you from truly offensive code.

The CRAP metric combines cyclomatic complexity and code coverage from automated tests (e.g. [PHPUnit] tests) to help you identify code that might be particularly difficult to understand, test, or maintain — the kind of code that makes developers say: This is crap! or, if they are stuck maintaining it, Oh, crap!.

The screenshot below shows how the CRAP metric is reported in the HTML code coverage report:

PHPUnit Development Moved to GitHub

nospam@example.com (Sebastian Bergmann) — Sat, 26 Dec 2009 11:45:00 +0100

Over the Christmas holidays I took a break from translating and editing the book on quality assurance in PHP projects that I am working on to finally migrate the code repository of PHPUnit from a self-hosted Subversion repository to a Git repository that is hosted on GitHub.

How did I get here?

I was staying at Arjen's place in Brisbane in August 2008 and one day we talked about distributed version control. Although I knew the basic concepts behind it, I was not yet convinced enough to take the plunge and try it out. Our discussion changed that, but it was not until my second trip to Australia later that year that I took the initial code for PHP_ObjectFreezer (which I had on my laptop since I started to hack on it together with Stefan on the flight to Atlanta for php|works 2008) and put it into a bzr repository on Launchpad. I grew comfortable enough with bzr quickly, but never really warmed up to Launchpad.

Around that time, I was hearing more and more positive things about Git and GitHub from my peers. So I took the PHP_ObjectFreezer code base and migrated it to Git and hosted the repository and GitHub to experiment with both the tool and the platform. It was a step that I did not regret and all the projects that I started since then are hosted on GitHub: bytekit-cli, phpcpd, phpdcd, phploc, PHP_CodeCoverage, PHP_FileIterator, PHP_ObjectFreezer, Text_Template, PHP_TokenStream.

Why did I do this?

Let me start with a quote from GitHub.com:

Git is a fast, efficient, distributed version control system ideal for the collaborative development of software.

GitHub is the easiest (and prettiest) way to participate in that collaboration: fork projects, send pull requests, monitor development, all with ease.

Over the last year, I have come to appreciate Git and GitHub a lot and also wanted to use them for PHPUnit.

Sure, I could have used git-svn for bi-directional operation between the existing Subversion repository and Git, but this would have always felt like only going half the way.

The arguments in favour of distributed version control systems are discussed by others far better than I could discuss them here, so I will just quote Ian Clatworthy's paper on distributed version control systems, in which discusses not only the technical differences between traditional version control systems and distributed version control systems, but also the differences with regard to development workflows and developer interaction:

Developers can collaborate directly without needing central authority or incurring central administration overhead
Developers can still be productive when the umbilical cord to their central VCS repository is broken, e.g. when travelling.
Creating and destroying branches are simple operations. This is particularly useful when experimenting with new ideas, e.g. a spike when using eXtreme Programming.

Ad-hoc collaboration with peers [is facilitated by] intelligent merge tracking [because] merging early and merging often is both possible and surprisingly unpainful. It is difficult to explain just how much of an impact this can make on how co-developers can work together more easily, e.g. when Pair Programming.

What does this mean for you?

PHPUnit is now hosted on GitHub.

In a nutshell, this means that the development of PHPUnit is now more open than it was before. If you want to contribute, you just need to fork PHPUnit on GitHub and create a topic branch for your contribution. Then let me know about your topic branch and I may or may not merge it.

If you are currently using svn:externals to pull PHPUnit into your own Subversion repository, you need to think about an alternative as PHPUnit's Subversion repository is no longer updated and will eventually go away.

How did I do it?

As this might be of interest to someone who wants to migrate his/her repository from Subversion to Git, here is how I performed the migration.

I started by creating a local mirror of the Subversion repository:

# Fetch Subversion repository
svnadmin create phpunit.svn
 
cat <<'EOF' > phpunit.svn/hooks/pre-revprop-change
#!/bin/sh
USER="$3"
 
if [ "$USER" = "svnsync" ]; then exit 0; fi
 
echo "Only the svnsync user can change revprops" >&2
exit 1
EOF
 
chmod +x phpunit.svn/hooks/pre-revprop-change
 
svnsync init \
  --username svnsync \
  file://`pwd`/phpunit.svn \
  svn://svn.phpunit.de/phpunit
 
svnsync sync \
  --username svnsync \
  file://`pwd`/phpunit.svn

Then I used svn2git for the actual migration:

# Create directory for Git repository
mkdir phpunit.git && cd phpunit.git
 
# Use svn2git to import repository
svn2git \
  --trunk trunk \
  --branches branches/release \
  --tags tags \
  --authors /home/sb/authors.txt \
  file:///home/sb/phpunit.svn/phpunit

After that I had to delete quite a few superfluous branches and tags, but that quickly dealt with. The final step was to create common ancestors for the master, 3.5, and 3.4 branches so that merging becomes easy and painless.

# Create 3.5 and 3.4 branches (in local repository)
git checkout remotes/origin/3.5 -b 3.5
git checkout remotes/origin/3.4 -b 3.4

# Create common ancestors for the master, 3.5, and 3.4 branches
git checkout 3.5 && git merge --strategy=ours master
git checkout 3.4 && git merge --strategy=ours 3.5

git checkout master && git merge --strategy=ours 3.5
git checkout 3.5 && git merge --strategy=ours 3.4

After that I had to delete quite a few superfluous branches and tags, but that quickly dealt with.

At this point I would like to thank David Soria Parra who helped me figure out some details here and there.

Update: GitHub now supports Subversion clients:

svn co https://svn.github.com/sebastianbergmann/phpunit

PHPUnit 3.4.2

nospam@example.com (Sebastian Bergmann) — Sun, 25 Oct 2009 15:55:00 +0100

I have released PHPUnit 3.4.2 today.

Besides the usual bug fixes, this release disables the backup and restore operations for static attributes (that was introduced in PHPUnit 3.4.0) by default.

The previous default setting caused too many problems with existing test suites (problems that would have been recognized earlier had users actually tested the PHPUnit 3.4 release candidates).

To enable the backup and restore operations for static attributes, simply pass the --static-backup command-line switch, use the @backupStaticAttributes annotation, or the XML configuration file.

Below is the full list of changes:

Fixed #889: --skeleton-class does not work with @depends annotation. [5270]
Fixed #902: PHPUnit_Util_File::getClassesInFile() does not handle nested namespaces correctly. [5272]
Fixed #905: Files with no methods or classes show incorrect code coverage with --coverage-clover. [5276] [5284]
Fixed #909: Stubbing a web service with getMockFromWsdl() throws a fatal error. [5281]
Fixed #918: Truncate operation throws an error. [5286]
The backup and restore operations for static attributes has been disabled by default. [5288]

PHPUnit 3.4.0

nospam@example.com (Sebastian Bergmann) — Wed, 16 Sep 2009 17:55:00 +0200

A year and a day has passed since the release of PHPUnit 3.3. Time to finally release PHPUnit 3.4.

Among the features introduced in this new version, the most notable are the support for test dependencies and fixture reuse as well as the possibility to run tests in separate PHP processes for increased test isolation. Please have a look at the ChangeLog for a complete list of changes.

Work on PHPUnit 3.5 has already started: the php-code-coverage project on GitHub is home to a refactoring of PHPUnit's code coverage functionality that will be one of the "hallmark features" of PHPUnit 3.5. It will also make PHPUnit's code coverage functionality available outside the scope of PHPUnit.

PHPUnit 3.4.0RC1

nospam@example.com (Sebastian Bergmann) — Tue, 18 Aug 2009 12:30:00 +0200

The first release candidate of PHPUnit 3.4 is now available.

Among the many new features introduced in this new version, the most notable are the support for test dependencies and fixture reuse as well as the possibility to run tests in separate PHP processes for increased test isolation. Please have a look at the ChangeLog for a complete list of changes.

You can help make PHPUnit 3.4 a "good release" by running your test suites with it and report any problems or regressions that you may encounter. You help is much appreciated!