Page 1 of 1

Hamcrest matchers ported for PHP 5

Posted: Wed Apr 01, 2009 10:00 am
by Chris Corbyn
I'd like to draw attention to the recent developments in Hamcrest that allow the matching library to be used within PHP 5 tests and applications.

Hamcrest is a matching library, primarily written in (and for) Java. It allows you to create complex expressions for matching values, such as the sort of matching you'd perform in a unit test case, or within a mock object library.

Hamcrest is the matching library used in the current version of jMock for Java and is well-established, easy to read (and use) and provides a very elegant error output for failed matches. The code has been ported to a number of languages, which now includes PHP.

Sebastian Bergmann, the author PHPUnit began this work some time ago, porting the library for PHP 5.3. I have backported this for PHP 5.2 in addition to porting most of the collections matchers with more PHP-specific names (array-centric rather than collection/map-centric).

You can use these matchers within any existing testing framework since they simply generate Exceptions for failed assertions. My need for porting however was primarily as the matching API for a mock object framework I'm in the process of rewriting (i.e. that assertThat() wrappers won't be used in my code.. only the underlying matchers will).

Currently the code is only in subversion (it's not in the tarball):

http://code.google.com/p/hamcrest

Some info:

http://code.google.com/p/hamcrest/wiki/TutorialPHP

If you've used the Java version then almost all of it is a literal translation.

Some quick examples:

Code: Select all

<?php
 
require_once 'hamcrest.php';
 
assertThat('a', equalTo('a'));
 
assertThat('a', is(equalTo('a')));
 
assertThat('A', not(equalTo('a')));
 
assertThat('A', is(not(equalTo('a'))));
 
assertThat('abcdef', startsWith('abc'));
 
assertThat('abcdef', endsWith('def'));
 
assertThat(3, greaterThan(1));
 
assertThat(2, lessThanOrEqualTo(6));
 
assertThat('a', lessThan('c'));
 
assertThat(array(1, 2, 3), hasItem(3));
 
assertThat(array('abc', 'def'), hasItem(endsWith('c')));
 
assertThat(array('a'=>'b', 'c'=>'d'), hasKey('c'));
 
assertThat(array('a'=>'b', 'c'=>'d'), hasKeyValuePair('a', 'b'));
 
assertThat('something', containsString('some'));
 
assertThat('something', both(containsString('some'))->andAlso(endWith('thing')));
 
assertThat('something', allOf(startsWith('s'), containsString('o'), endsWith('g')));
 
assertThat("some\r\n thing", is(equalToIgnoringWhitespace('some thing')));
 
Errors look something like:

[text]Expected: a value less than <1.3F>     but: <2.7F> was greater than <1.3F>  Expected: "hello"     but: was "hi"  Expected: a string starting with "bar"     but: was "foobar"  Expected: is an array with size <7>     but: array size was <3> [/text]

All the functions are listed in the hamcrest.php file for a full-overview.