Testing output (Intermediate)

While PHP started out as a web-based scripting language, over the years it has become more and more common for command line scripts to be created as well. One of the common pieces of functionality for these scripts is the output of text to the command line. While one could make the argument that testing the output falls outside of the realm of unit testing, it does not fall outside of the realm of PHPUnit's functionality.

PHPUnit makes it very simple to capture and validate text that has been output to the command line.

How to do it...

The following code echoes text to the command line.

<?php
class CliFormatter
{
  // ...
  public function announcePlayerHand(Player $player)
  {
    echo "Current Hand: ", $this->getCards($player->getHand()), "\n\n";
  }
  // ...
}

This code can be tested to ensure it outputs what you would expect with the following code below:

<?php
class CliFormatterTest extends PHPUnit_Framework_TestCase
{
  private $formatter;

  public function setUp()
  {
    $this->formatter = new CliFormatter();
  }

  public function testAnnouncePlayerHand()
  {
    $cards = new CardCollection();
    $cards->addCard(new Card('A', 'Spades'));
    $cards->addCard(new Card('2', 'Spades'));

    $player = $this->getMock('HumanPlayer', array(), array(), '', false);
    $player->expects($this->once())
      ->method('getHand')
      ->will($this->returnValue($cards));

    $this->expectOutputString("Current Hand: AS 2S \n\n");
    $this->formatter->announcePlayerHand($player);
  }
}

How it works...

The expectOutputString() method can be used to determine if your code is outputting what you expect to the command line. PHPUnit uses PHP's output buffering functionality to capture anything that is sent to the script's stdout command. The expectOutputString() method will compare the string you pass to it to the buffer at the end of the test. If the values do not match, PHPUnit will fail that test.

You can also match the output with a regular expression using expectedOutputRegex(). We could rewrite the expectedOutputString() call as follows:

$this->expectOutputRegex('/^Current Hand: AS 2S\s+$/');

This is a convenient way to help get rid of the sensitivity to white spaces that expectedOutputString() has. A better way to handle a white space in your output is to use setOutputCallback(). This method can be used to manipulate the output before it is checked against the expectations set by expectedOutputRegex() or expectedOutputString(). One of these manipulations could be to trim all whitespace:

public function testAnnouncePlayerHandCallback()
{
  $cards = new CardCollection();
  $cards->addCard(new Card('A', 'Spades'));
  $cards->addCard(new Card('2', 'Spades'));

  $player = $this->getMock('HumanPlayer', array(), array(), '', false);
  $player->expects($this->once())
      ->method('getHand')
      ->will($this->returnValue($cards));

  $this->expectOutputString("Current Hand: AS 2S");
  $this->setOutputCallback(function ($output) {
    return trim($output);
  });
  $this->formatter->announcePlayerHand($player);
}

There's more...

When PHPUnit is running in the strict mode it will emit an error whenever the test writes an output to the screen. To prevent this from happening you simply need to turn off the strict mode in the XML configuration and discontinue the use of the --strict command line flag when running the test suite.