I spent the better part of yesterday and today working out the last of the kinks and I am pretty happy with the results. It provides a great alternative mocking framework for PHPUnit that is compatible not just with older versions of PHPUnit but also older versions of PHP (5.2). You can look through my blog for some of my initial posts about it, or you can peruse the Phake documentation. It allows you to do quite a few nifty things.

A big thanks to all those who have contributed feedback / code thus far.

Happy new year!

Also, a couiple quick little side notes, the only reason I am still considering this an alpha is the lack of exhaustive, centralized documentation. The Phake Wiki has some good details as does my previous post but I would like to get more official documentation up soon at which put it into a full beta. The api right now should be considered stable however. It will not be changing short of huge issues. We have been using it in production testing at my company for a little while no with great success. So, if the label of ‘alpha’ makes you nervous, don’t worry. It’ll be okay.

Lastly, this library is compatible with PHP 5.2. I never really mentioned that in my last post either. It is not currently utilizing any php 5.3 functionality and I have no plans to break this backwards compatibility any time soon.

Over the last three years, my experience as well as the musing of some of my colleagues has led me to believe that a lot of what I don’t like about mocking in php is the result of the fundamental notions of combining stubbing with verification and setting expectations ahead of method calls instead of verifying that what you expected to happen has indeed happened. This was essentially proven to me over the last year and a half as I have been heavily working with Java code and as a result have been using the Mockito mocking library for Java. The result of this work is the Phake Mocking Framework.

Now I am fairly certain that at least 5 or 6 people (which may constitute everyone who reads this) are rolling their eyes by now. So instead of going further into why I like this style of mocking I’ll just show you how to use it. Phake was designed with PHPUnit in mind, however I don’t really see any reason why it couldn’t be used in other testing frameworks as well. It is on my roadmap to confirm support for other frameworks. In any case, I will be using PHPUnit for my examples.

This document assumes you already have a good understanding of the basics of mocking. If the terms ‘Mocking’, ‘Stubbing’, and ‘Test Doubles’ mean nothing to you, I would recommend checking out the following links:

• PHPUnit on Mock Objects
• Wikipedia on Mock Objects
• The Universe on Mock Objects

Getting Started

You can get a copy of Phake from Github. If you are familiar and comfortable with with git you can just clone my repository. If you would rather avoid the trappings of Github, you can also download Phake’s latest release tarball. Either way will result in a directory with two subdirectories: src and test. You will want to move the contents of the src directory to somewhere in your include path (such as /usr/share/php). Once you have done this, you can simply include “Phake.php” in any of your tests or in your bootstrap script and you will be off to the races.

UPDATE!!!

I just set up a pear channel to distribute phake as well. So if you would like to install Phake using pear, just do the following:

To show you some of the basics of how to use this framework, I am going to write various bits of codes to mock, verify, stub, etc the following class:

Stubbing

You can also do conditional stubbing based on passed in parameters.

If a specific invocation or call of a mock object has not been stubbed, it will return null. This behavior is different than the default behavior of PHPUnit’s mocking framework. If you need the default PHPUnit behavior then you could use something called partial mocks. Partial mocks are setup to call the constructor of the class being mocked and for any call that has not been stubbed, the parent method will be called.

You can also specify on a per call basis that you want to call the parent, using the thenCallParent() method instead of thenReturn(). The different values you can use for stubbing are referred to as ‘Answers’. Here are a list of them and what they will do when a matching invocation is called:

• thenReturn(mixed $var) – Will return the exact value passed in.
• thenCallParent() – Will return the results of calling the mocked parent method.
• thenThrow(Exception $e) – Will throw $e.
• captureReturnTo(&$variable) – Acts exactly like thenCallParent() however it also captures the value that the parent returned to $variable. This allows you to run assertions. This comes in very handy for testing legacy code with protected or private factory methods whose return values are never returned out of the tested method’s scope.

The other thing to take note of stubbing is that any PHPUnit constraints are supported.

This gives you the same kind of stubbing flexibility that you have present in PHPUnit.

Verification

Verifying that methods on your stub are called is starkly different then how it is done in PHPUnit. The most apparent symptom of this difference is that you verify calls after the calls to your test methods have been made.

You of course have the same matching functionality at your disposal.

By default, verify only allows a single matching invocation. You can also specify that a specific number of invocations should be allowed.

You can also use Phake::atLeast($n) and Phake::atMost($n) instead of Phake::times($n).

You can also specify that you don’t expect there to be any interactions with a mock.

I am sure you noticed the comment that Phake::verifyNoInteraction() only verifies that no calls were made up to that point. You can essentially freeze a mock with another method

There are a few more advanced things you can do with something called argument captors.

This is a very pedestrian example, but it is not that uncommon for fairly complicated objects to passed in and out of methods. Argument capturing allows you to much more succinctly assert the state of those types of parameters. It is definitely overkill for asserting scalar types or simple objects.

More to Come

This really does cover the very basics of the Phake framework. In the coming days I will be putting out smaller more focused articles discussing some of the specific functionality. In the meantime I would love to get some feedback from anyone who is brave enough to play with this. My future roadmap basically involves shoring up the current code base a little bit more, adding a few pieces of missing or suboptimal functionality (I’m not so sure I have implemented ‘consecutive calls’) but I anticipate releasing an RC version no later than the end of January. Also, I am currently using and monitoring the issue tracker for Phake at github, so if you have some functionality you would like or find any bugs in your exploring, you can also open an issue there. Also, if you would like to help out with contributions, they are certainly welcome.

This is really the first I have dealt with YAML and it is definitely a viable alternative for data sets. Here is what they will look like.

The biggest issue I had was figuring out how YAML dealt with trailing line breaks. It appears that ‘|-’ did the trick. It will strip the final line break. Another thing to take note is that indention is important. It doesn’t HAVE to be spaces (it can be tabs) it just needs to be consistent. The last thing is that strings do not need to be quoted, but if they are you can use escape characters (like \n.)

This was committed to the trunk of PHPUnit and I anticipate Sebastian will be merging it back into 3.4 shortly.

For instance, if you wanted to specify an include filter you can do the following:

I have also deprecated passing the filter to the constructor. The reason for this is that I would like to begin adding a few more features to the filter and the current method of passing the parameters on the constructor would be unintuitive for these planned features. Basically I think it was a mistake for me to allow the passing of filter data on the constructor to begin with. I anticipate the current method working up to PHPUnit 4.0 but it will not be expanded on and will be removed either in PHPUnit 4 or in a release soon after that.

So, for exclude filters, instead of specifying them in the constructor, the new method will be:

While you can’t mix include and exclude filters for tables (wouldn’t make sense right now) you CAN do this for table columns of separate tables:

Some future features I plan on adding include, global column includes/excludes and wild cards. Anyhow, hope this is useful for someone.

Please continue reading to see how you can use composition to add database tests to your existing test cases.

So, now you might be wondering how can I use this class to add data-centric tests to my existing test case. I am going to use the BankAccount example that exists in PHPUnit to show you. Below you can find the existing bank account test case (without comments.)

I would like to add a test to see if a bank account is created in the database when the bank account’s constructor is called. This is the same test I showed you in my first example of the database extension. However, I do not want to add the overhead of creating and seeding the database for my existing tests that obviously doesn’t need them. I should tell you right away that I would actually prefer in these cases to just create a new test case to handle just the data-centric tests. However, one thing using composition will assist greatly with is if you want to test database code that should throw exceptions as well as perform data operations. I am sure there are many other valid uses that I haven’t even thought of as well.

First thing I need to do is add an instance of PHPUnit_Extensions_Database_DefaultTester to the test case. To create a tester instance I will need to have a pdo connection. For this example I am going to use a database I created on my local machine in mysql.

I will now need to specify the different events that will occur on startUp and tearDown of the new test and the data that will be used. To do this I am going to add a few calls to the tester in my getDatabaseTester() method. The first method, setSetUpOperation(), will tell the tester which operation I would like to perform on the database at the start of each test. Likewise, the second method setTearDownOperation() will tell the tester which operation to perform on the database at the end of each test. Both of these methods will accept an object implementing PHPUnit_Extensions_Database_Operation_IDatabaseOperation. The most common one you will probably want to use is the ‘clean insert’ operation. This operation will perform a truncate on each table in your data set and then insert all rows in the dataset. I am going to use a factory class to generate the operation. If you want to view all of the current operations available I recommend browsing the following src directory: http://www.phpunit.de/browser/phpunit/branches/3.2/PHPUnit/Extensions/Database/Operation. The final method we will need to call is setDataSet(). This will
accept any of the data set objects. I am just going to use a flat xml data set with a few rows.

So with these new changes our getDatabaseTester() method will look like this:

You will notice that I used an operation called NONE() on teardown. This, as you may have guessed, is a NULL operation. It does absolutely nothing which in this case is perfectly alright since we are truncating at the the beginning of each test.

Now I am ready to add my new test method. In this test I am going to call my getDatabaseTester(). I will the call the onSetUp() method of the tester. This will perform the setup operation that we specified previously. Then I will create a new bank account, retrieve a dataset from the connection I created in getDatabaseTester() (utilizing the getConnection() method,) and compare the results using the assertDataSetsEqual() static method of the Database TestCase class. Finally I will clean up my mess (which in this case means nothing) using the onTearDown() method of the tester object.

You will notice that I have access to the two asserts of the database test case. They are static, public methods and can be accessed from anywhere.

That’s all there is to it. Now you can just go nuts adding new database tests or plain old php tests only incurring the database overhead when needed.

For those that may not have read any of my previous postings on the subject the goal of this software is to extend the functionality of PHPUnit to allow using seed data to put a given database into a known state prior to executing each test. It also provides an easy mechanism to compare database contents with an expected dataset.

The database extension has recently been merged into the PHPUnit 3.2 branch and is scheduled to be released in that version. Sebastian Bergmann will be introducing the extension in his Advanced Testing with PHPUnit talk at PHP|Works 2007 in Atlanta September 13 – 14. If you would like to tinker around with the database extension prior to it’s release you can always download the latest copy of PHPUnit 3.2 from svn: svn://svn.phpunit.de/phpunit/phpunit/branches/3.2. The source can also be browsed at http://www.phpunit.de/browser/phpunit/branches/3.2/PHPUnit/Extensions/Database.

Please continue reading for an example of how you can now use PHPUnit to even more effectively test data-centric applications.

In this example I am going show you how to create a new test case to test the database functionality of a class providing functionality to edit the details of a bank account.

To use the database extension I will create a new test case extending the class PHPUnit_Extensions_Database_TestCase.

There are two methods that you must have in any database test case. Those methods are getConnection() and getDataSet(). The first method getConnection() must return an object that implements the PHPUnit_Extensions_Database_DB_IDatabaseConnection interface. In most cases you will return an instance of the PHPUnit_Extensions_Database_DB_DefaultDatabaseConnection. The constructor for this class takes two parameters. The first is a PDO object that is connected to the database you plan on using to test your functionality. The second parameter is the name of the database schema you will be testing against. I realize that PHPUnit_Extensions_Database_DB_DefaultDatabaseConnection is a handful to type so there is a helper method in the TestCase class that will instantiates a database connection with the same arguments: createDefaultDBConnection(PDO $connection, string $schema).

You can choose a variety of methods to get the PDO object to pass to this method. For this example I will create the connection in the test case constructor and add it as a protected class property. For large test suites you may want to use a static singleton method of a test utility class to help get rid of some of the overhead of opening and closing connections. Here is our test case with the getConnection() method implemented:

For my test I have simply chosen to use the memory database in sqlite. I have chosen this simply because it is faster than an sqlite database in the filesystem and this is just a tutorial so persistence of the file is simply not needed. I have called the BankAccount::createTable() method to create the schema that the BankAccount object uses. The downside to using the memory database is you have to create your schema every time. Normally you would have a persistant database for testing that would always have the necessary schema to test your code. Note that when using sqlite what you pass as the $schema parameter does not really matter since sqlite does not really have the concept of schemas.

This brings us to the next required method. The getDataSet() method is used to return the seed data that is used in setUp() and tearDown() operations for each test. There are currently two different ways to easily load datasets: the Flat XML DataSet and the XML DataSet. The flat XML data set is an extremely simple yet somewhat limited data set where the XML data set is slightly more complicated but much more robust when dealing with null values. For our example we will use the flat xml data set.

In the flat xml data set you create a root element named dataset and then create xml element for every row in every table of your database. The element name is equal to the table name the row resides in. The element will have one attribute for each column in the table. If there is an attribute missing for one element that exists in another element then that colum for the row with the missing attribute will be set to NULL. Please note that colname="" will not set that column to null. It will set it to an empty string (or whatever that translates to for that articular column’s data type.

The flat xml data set we will be using is as follows:

The classname of the flat xml data set is PHPUnit_Extensions_Database_DataSet_FlatXMLDataSet and it’s only argument is the path to xml file that you are loading. Once again, this is an astronomically long class name so there is a helper method to instantiate this class: createFlatXMLDataSet().

Here is our test case with the getDataSet() method implemented:

Now in a default implementation the database extension will perform a ‘clean insert’ operation on your database using the the dataset returned by getDataSet. The clean insert operation will truncate any tables in the data set (not all tabes in the database) and then insert the rows in the dataset. The default implementation will do nothing on tear down. There are several other operations that can be used by adding the getSetUpOperation() and getTearDownOperation() methods. These methods should return a PHPUnit_Extensions_Database_Operation_* class. These operations can be returned using the test case’s getOperations() method. The default set up implementation is the equivelant of creating the following getSetUpOperation().

There is one more thing to take note of before we dive into our first test. The Database_Testcase is heavily dependant on it’s implementation of setUp() and tearDown() for it’s functionality to work. If you need to perform additional setup or teardown actions make sure you call the parent versions of these functions as well.

The functionality I would like to test in this example is testing new account creation. In the bank account class, whenever a new BankAccount class is instantiated it is supposed to create a new bank account with a zero balance in the database. To test this we will need to create another dataset representing our seed data with the expected changes.

Using this data set we can create a new test that instantiates a bank account object and then we will assert that the contents of the database are equal to the dataset we just created. In order to compare the database to your dataset you need to create a dataset containing the contents of your database. This is done by calling the createDataSet() method of the database connection object you created in the getConnection() method. You can then pass it to the assertDataSetsEqual() function. Also notice that you can just reuse the createFlatXMLDataSet() method to load the expected dataset.

If you have a large database data set you can also compare at the table level using the test case method assertTablesEqual(). You can pass it individual tables by calling the getTable($tableName) method. This method exists for any of the data set classes. You can also limit tables at the database level by passing an array of table names to the createDataSet() method. So if your database had multiple tables the above function could have been rewritten as below to only compare at the table level.

Or if you didn’t even want to bother loading tables you won’t be testing against:

Hopefully that is enough to pique your interest. As always, if you have any questions feel free to ask me.

I would have to say that after a few weeks of tinkering with it I am impressed. Now, keep in mind that I am talking about software that is still in development, so a degree of lattitude is required. The featureset of PHPUnit 3 is great. Here are a few notable features (in my mind):

• Mock objects
• Code Coverage Analysis
• Multitude of test logging options
• Built well for testing >php5 applications

Using the framework is an absolute breeze and there is excellent documentation in the form of a free book (draft version) written by Sebastian Bergmann and published by O’Reilly called "PHPUnit Pocket Guide." The API is also documented quite nicely and serves as a good second-source for learning how to do specific things.

The most impressive part of this experience in my mind was how runnable the software is straight out of CVS. Most of the time when I am crazy enough to use CVS version I always seem to get my copy of the source at a point where it is very unstable and requires tweaking just to get the software to fulfill its basic requirements. PHPUnit 3 on the other hand was able to run in it’s standard mode without a flaw. The only thing that was missing that I felt I needed was html reports for the pass/fail status of the unit tests. The report templates and code was already to a point however that it was actually fairly trivial for me to make the changes to it that I thought would be needed to make it work. I have since passed those changes along to Sebastian and they have been added to CVS, so html reports are now in the cvs version as well. It felt good to be able to contribute a little bit to a very worthwhile project.

Sebastian has posted about the new reporting features on his blog that include some screenshots so I won’t bother to rehash over all of that. You can just go check them out on his site.