Section 15-2.  PHPUnit2_Framework_Assert

15-2. PHPUnit2_Framework_Assert

Most test cases written for PHPUnit are derived indirectly from the class PHPUnit2_Framework_Assert, which contains methods for automatically checking values and reporting discrepancies. The methods are declared static, so you can write design-by-contract style assertions in your methods and have them reported through PHPUnit (Example 19).

Example 19. Design-by-contract style assertions

<?php
require_once 'PHPUnit2/Framework/Assert.php';

class Sample {
  public function aSampleMethod($object) {
    PHPUnit2_Framework_Assert::assertNotNull($object);
  }
}
$sample = new Sample;
$sample->aSampleMethod(NULL);
?>
Fatal error: Uncaught exception
  'PHPUnit2_Framework_AssertionFailedError'
with message 'expected: <NOT NULL> but was: <NULL>'

Most of the time, though, you'll be checking the assertions inside of tests.

There are two variants of each of the assertion methods: one takes a message to be displayed with the error as a parameter, and one does not. Example 20 demonstrates an assertion method with a message. The optional message is typically displayed when a failure is displayed, which can make debugging easier.

Example 20. Using assertions with messages

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
class MessageTest extends PHPUnit2_Framework_TestCase {
  public function testMessage( ) {
    $this->assertTrue(FALSE, 'This is a custom message.');
  }
}
?>

The following example shows the output you get when you run the testMessage( ) test from Example 20, using assertions with messages:

phpunit MessageTest.php
PHPUnit 2.3.0 by Sebastian Bergmann.

F

Time: 0.102507
There was 1 failure:
1) testMessage(MessageTest)
This is a custom message.

FAILURES!!!
Tests run: 1, Failures: 1, Errors: 0, Incomplete Tests: 0.

Table 6 shows all the varieties of assertions.

Table 6. Assertions

Assertion	Description
void assertTrue(Boolean $condition)	Reports an error if $condition is FALSE.
void assertTrue(Boolean $condition, String $message)	Reports an error identified by $message if $condition is FALSE.
void assertFalse(Boolean $condition, String $message)	Reports an error identified by $message if $condition is trUE.
void assertNull(Mixed $variable)	Reports an error if $variable is not NULL.
void assertNull(Mixed $variable, String $message)	Reports an error identified by $message if $variable is not NULL.
void assertNotNull(Mixed $variable)	Reports an error if $variable is NULL.
void assertNotNull(Mixed $variable)	Reports an error if $variable is NULL.
void assertNotNull(Mixed $variable, String $message)	Reports an error identified by $message if $variable is NULL.
void assertSame(Object $expected, Object $actual)	Reports an error if the two variables $expected and $actual do not reference the same object.
void assertSame(Object $expected, Object $actual, String $message)	Reports an error identified by $message if the two variables $expected and $actual do not reference the same object.
void assertSame(Mixed $expected, Mixed $actual)	Reports an error if the two variables $expected and $actual do not have the same type and value.
void assertSame(Mixed $expected, Mixed $actual, String $message)	Reports an error identified by $message if the two variables $expected and $actual do not have the same type and value.
void assertNotSame(Object $expected, Object $actual)	Reports an error if the two variables $expected and $actual reference the same object.
void assertNotSame(Object $expected, Object $actual, String $message)	Reports an error identified by $message if the two variables $expected and $actual reference the same object.
void assertNotSame(Mixed $expected, Mixed $actual)	Reports an error if the two variables $expected and $actual have the same type and value.
void assertNotSame(Mixed $expected, Mixed $actual, String $message)	Reports an error identified by $message if the two variables $expected and $actual have the same type and value.
void assertEquals(Array $expected, Array $actual)	Reports an error if the two arrays $expected and $actual are not equal.
void assertEquals(Array $expected, Array $actual, String $message)	Reports an error identified by $message if the two arrays $expected and $actual are not equal.
void assertNotEquals(Array $expected, Array $actual)	Reports an error if the two arrays $expected and $actual are equal.
void assertNotEquals(Array $expected, Array $actual, String $message)	Reports an error identified by $message if the two arrays $expected and $actual are equal.
void assertEquals(Float $expected, Float $actual, Float $delta = 0)	Reports an error if the two floats $expected and $actual are not within $delta of each other.
void assertEquals(Float $expected, Float $actual, String $message, Float $delta = 0)	Reports an error identified by $message if the two floats $expected and $actual are not within $delta of each other.
void assertNotEquals(Float $expected, Float $actual, Float $delta = 0)	Reports an error if the two floats $expected and $actual are within $delta of each other.
void assertNotEquals(Float $expected, Float $actual, String $message, Float $delta = 0)	Reports an error identified by $message if the two floats $expected and $actual are within $delta of each other.
void assertEquals(String $expected, String $actual)	Reports an error if the two strings $expected and $actual are not equal. The error is reported as the delta between the two strings.
void assertEquals(String $expected, String $actual, String $message)	Reports an error identified by $message if the two strings $expected and $actual are not equal. The error is reported as the delta between the two strings.
void assertNotEquals(String $expected, String $actual)	Reports an error if the two strings $expected and $actual are equal.
void assertNotEquals(String $expected, String $actual, String $message)	Reports an error identified by $message if the two strings $expected and $actual are equal.
void assertEquals(Mixed $expected, Mixed $actual)	Reports an error if the two variables $expected and $actual are not equal.
void assertEquals(Mixed $expected, Mixed $actual, String $message)	Reports an error identified by $message if the two variables $expected and $actual are not equal.
void assertNotEquals(Mixed $expected, Mixed $actual)	Reports an error if the two variables $expected and $actual are equal.
void assertNotEquals(Mixed $expected, Mixed $actual, String $message)	Reports an error identified by $message if the two variables $expected and $actual are equal.
void assertContains(Mixed $needle, Array $haystack)	Reports an error if $needle is not an element of $haystack.
void assertContains(Mixed $needle, Array $haystack, String $message)	Reports an error identified by $message if $needle is not an element of $haystack.
void assertNotContains(Mixed $needle, Array $haystack)	Reports an error if $needle is an element of $haystack.
void assertNotContains(Mixed $needle, Array $haystack, String $message)	Reports an error identified by $message if $needle is an element of $haystack.
void assertContains(Mixed $needle, Iterator $haystack)	Reports an error if $needle is not an element of $haystack.
void assertContains(Mixed $needle, Iterator $haystack, String $message)	Reports an error identified by $message if $needle is not an element of $haystack.
void assertNotContains(Mixed $needle, Iterator $haystack)	Reports an error if $needle is an element of $haystack.
void assertNotContains(Mixed $needle, Iterator $haystack, String $message)	Reports an error identified by $message if $needle is an element of $haystack.
void assertRegExp(String $pattern, String $string)	Reports an error if $string does not match the regular expression $pattern.
void assertRegExp(String $pattern, String $string, String $message)	Reports an error identified by $message if $string does not match the regular expression $pattern.
void assertNotRegExp(String $pattern, String $string)	Reports an error if $string matches the regular expression $pattern.
void assertNotRegExp(String $pattern, String $string, String $message)	Reports an error identified by $message if $string matches the regular expression $pattern.
void assertType(String $expected, Mixed $actual)	Reports an error if the variable $actual is not of type $expected.
void assertType(String $expected, Mixed $actual, String $message)	Reports an error identified by $message if the variable $actual is not of type $expected.
void assertNotType(String $expected, Mixed $actual)	Reports an error if the variable $actual is of type $expected.
void assertNotType(String $expected, Mixed $actual, String $message)	Reports an error identified by $message if the variable $actual is of type $expected.

You may find that you need other assertions than these to compare objects specific to your project. Create your own Assert class to contain these assertions to simplify your tests.

Failing assertions all call a single bottleneck method, fail(String $message), which throws a PHPUnit2_Framework_ AssertionFailedError. There is also a variant that takes no parameters. Call fail( ) explicitly when your test encounters an error. The test for an expected exception is an example. Table 7 lists the bottleneck methods in PHPUnit.

Table 7. Bottleneck methods

Method	Description
void fail( )	Reports an error.
void fail(String $message)	Reports an error identified by $message.