Testing exceptions and errors (Intermediate)

A negative test is a test that is created to show error conditions or exceptions from the system under test. Negative tests can be easy to ignore. However, it is not only important to make sure your code works the way it is supposed to but it is also important to know that it also fails the way it is supposed to.

Fortunately, PHPUnit provides very easy to use functionality to help ensure that your code is throwing errors and exceptions at the appropriate time.

How to do it...

This functionality can be shown through some negative tests for the following code:

<?php
abstract class Player
{
  // ...

  public function requestCard()
  {
    $cardNumber = $this->chooseCardNumber();

    if (!$this->hasCard($cardNumber))
    {
      throw new RuntimeException('Invalid card chosen by player');
    }

    return $cardNumber;
  }

  // ...
}

To properly test that the exception is being thrown we can write the following test:

<?php
class PlayerTest extends PHPUnit_Framework_TestCase
{
  public function testRequestCardThrowsOnInvalidCard()
  {
    $this->player->expects($this->once())
        ->method('chooseCardNumber')
        ->will($this->returnValue('2'));

    $this->setExpectedException('RuntimeException', 'Invalid card chosen by player');
    $this->player->requestCard();
  }
}

How it works...

You can test that your code throws an exception using the setExpectedException() method. This tells PHPUnit to make sure that a specified exception is thrown before the test is finished. It takes the fully qualified class name of the exception as the first parameter. You can specify an optional second and third parameter with the expected message and code for the exception. If either of these parameters are not specified then the message and code will not be checked.

In this test, you are setting up the player class to choose a card number that does not currently exist in the hand. When this occurs a RuntimeException should be thrown with the message Invalid card chosen by player when Player::requestCard() is called. In the event that the error doesn't get thrown the test will fail.

There's more...

PHPUnit also allows you to specify expected exceptions using annotations.

/**
 * @expectedException RuntimeException
 * @expectedExceptionMessage Invalid card chosen by player
 */
public function testRequestCardThrowsOnInvalidCardUsingAnnotation()
{
  $this->player->expects($this->once())
      ->method('chooseCardNumber')
      ->will($this->returnValue('2'));

  $this->player->requestCard();
}

Instead of using the setExpectedException() method you can use the @expectedException annotation. The @expectedException annotation accepts the fully qualified class name of the exception that should be thrown. The @expectedExceptionMessage annotation accepts the message that should be set on the exception. There is also an @expectedExceptionCode annotation that can be used to set an exception code if necessary.