Chapter 5. The Command-Line Test Runner

The PHPUnit command-line test runner can be invoked through the phpunit command. The following code shows how to run tests with the PHPUnit command-line test runner:

phpunit ArrayTest
PHPUnit 3.2.10 by Sebastian Bergmann.

..

Time: 0 seconds


OK (2 tests)

For each test run, the PHPUnit command-line tool prints one character to indicate progress:

.: Printed when the test succeeds.
F: Printed when an assertion fails while running the test method.
E: Printed when an error occurs while running the test method.
S: Printed when the test has been skipped (see Chapter 10).
I: Printed when the test is marked as being incomplete or not yet implemented (see Chapter 10).

PHPUnit distinguishes between failures and errors. A failure is a violated PHPUnit assertion such as a failing assertEquals() call. An error is an unexpected exception or a PHP error. Sometimes this distinction proves useful since errors tend to be easier to fix than failures. If you have a big list of problems, it is best to tackle the errors first and see if you have any failures left when they are all fixed.

Let's take a look at the command-line test runner's switches in the following code:

phpunit --help
PHPUnit 3.2.10 by Sebastian Bergmann.

Usage: phpunit [switches] UnitTest [UnitTest.php]

  --log-graphviz <file>  Log test execution in GraphViz markup.
  --log-json <file>      Log test execution in JSON format.
  --log-tap <file>       Log test execution in TAP format to file.
  --log-xml <file>       Log test execution in XML format to file.
  --log-metrics <file>   Write metrics report in XML format.
  --log-pmd <file>       Write violations report in PMD XML format.

  --coverage-html <dir>  Generate code coverage report in HTML format.
  --coverage-xml <file>  Write code coverage information in XML format.

  --test-db-dsn <dsn>    DSN for the test database.
  --test-db-log-rev <r>  Revision information for database logging.
  --test-db-prefix ...   Prefix that should be stripped from filenames.
  --test-db-log-info ... Additional information for database logging.

  --testdox-html <file>  Write agile documentation in HTML format to file.
  --testdox-text <file>  Write agile documentation in Text format to file.

  --filter <pattern>     Filter which tests to run.
  --group ...            Only runs tests from the specified group(s).
  --exclude-group ...    Exclude tests from the specified group(s).

  --loader <loader>      TestSuiteLoader implementation to use.
  --repeat <times>       Runs the test(s) repeatedly.

  --tap                  Report test execution progress in TAP format.
  --testdox              Report test execution progress in TestDox format.

  --no-syntax-check      Disable syntax check of test source files.
  --stop-on-failure      Stop execution upon first error or failure.
  --verbose              Output more verbose information.
  --wait                 Waits for a keystroke after each test.

  --skeleton             Generate skeleton UnitTest class for Unit in Unit.php.

  --help                 Prints this usage information.
  --version              Prints the version and exits.

  --configuration <file> Read configuration from XML file.
  -d key[=value]         Sets a php.ini value.

phpunit UnitTest

Runs the tests that are provided by the class UnitTest. This class is expected to be declared in the UnitTest.php sourcefile.

UnitTest must be either a class that inherits from PHPUnit_Framework_TestCase or a class that provides a public static suite() method which returns an PHPUnit_Framework_Test object, for example an instance of the PHPUnit_Framework_TestSuite class.

phpunit UnitTest UnitTest.php

Runs the tests that are provided by the class UnitTest. This class is expected to be declared in the specified sourcefile.

--log-graphviz

Generates a logfile using the GraphViz markup for the tests run. The generated logfile can be rendered using the dot tool, for instance. See Chapter 16 for more details.

Please note that this parameter is only available when the Image_GraphViz PEAR package is installed.

--log-json

Generates a logfile using the JSON format. See Chapter 16 for more details.

--log-tap

Generates a logfile using the Test Anything Protocol (TAP) format for the tests run. See Chapter 16 for more details.

--log-xml

Generates a logfile in XML format for the tests run. See Chapter 16 for more details.

--log-metrics

Generates a logfile in XML format with the software metrics for the system under test.

Please note that this parameter is only available when the tokenizer and Xdebug extensions are installed.

--log-pmd

Generates a logfile in XML format with violations of rules that are, for instance, based on software metrics.

Please note that this parameter is only available when the tokenizer and Xdebug extensions are installed.

--coverage-xml

Generates a logfile in XML format with the code coverage information for the tests run. See Chapter 16 for more details.

Please note that this parameter is only available when the tokenizer and Xdebug extensions are installed.

--coverage-html

Generates a code coverage report in HTML format. See Chapter 14 for more details.

Please note that this parameter is only available when the tokenizer and Xdebug extensions are installed.

--charset

Specifies the character set to be used with --report.

--test-db-*

Writes test result and code coverage data to a database. See Chapter 16 for more details.

Please note that this parameter is only available when the PDO extension is installed.

--testdox-html and --testdox-text

Generates agile documentation in HTML or plain text format for the tests that are run. See Chapter 15 for more details.

--filter

Only runs tests whose name matches the given pattern. The pattern can be either the name of a single test or a regular expression that matches multiple test names.

--group

Only runs tests from the specified group(s). A test can be tagged as belonging to a group using the @group annotation.

--exclude-group

Exclude tests from the specified group(s). A test can be tagged as belonging to a group using the @group annotation.

--loader

Specifies the PHPUnit_Runner_TestSuiteLoader implementation to use.

The standard test suite loader will look for the sourcefile in the current working directory and in each directory that is specified in PHP's include_path configuration directive. Following the PEAR Naming Conventions, a class name such as Project_Package_Class is mapped to the sourcefile name Project/Package/Class.php.

--repeat

Repeatedly runs the test(s) the specified number of times.

--stop-on-failure

Stop execution upon first error or failure.

--no-syntax-check

Disables the syntax check of test source files.

--tap

Reports the test progress using the Test Anything Protocol (TAP). See Chapter 16 for more details.

--testdox

Reports the test progress as agile documentation. See Chapter 15 for more details.

--verbose

Output more verbose information, for instance the names of tests that were incomplete or have been skipped.

--wait

Waits for a keystroke after each test. This is useful if you are running the tests in a window that stays open only as long as the test runner is active.

--skeleton

Generates a skeleton test-case class UnitTest (in UnitTest.php) for a class Unit (in Unit.php). See Chapter 17 for more details.

--configuration

Read configuration from XML file. See Appendix B for more details.

-d

Sets the value of the given PHP configuration option.

Note

When the tested code contains PHP syntax errors, the TextUI test runner might exit without printing error information. The standard test suite loader will check the test suite sourcefile for PHP syntax errors, but not sourcefiles included by the test suite sourcefile.

1. Automating Tests

2. PHPUnit's Goals

3. Installing PHPUnit

4. Writing Tests for PHPUnit