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 2.3.0 by Sebastian Bergmann.
..
Time: 0.067288
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.
I
Printed when the test is marked as being incomplete or not yet implemented (see Chapter 7).
PHPUnit distinguishes between failures and errors. A failure is a violated PHPUnit assertion. 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 2.3.0 by Sebastian Bergmann.
Usage: phpunit [switches] UnitTest [UnitTest.php]
--coverage-data <file> Write Code Coverage data in raw format to file.
--coverage-html <file> Write Code Coverage data in HTML format to file.
--coverage-text <file> Write Code Coverage data in text format to file.
--testdox-html <file> Write agile documentation in HTML format to file.
--testdox-text <file> Write agile documentation in Text format to file.
--log-xml <file> Log test progress in XML format to file.
--loader <loader> TestSuiteLoader implementation to use.
--skeleton Generate skeleton UnitTest class for Unit in Unit.php.
--wait Waits for a keystroke after each test.
--help Prints this usage information.
--version Prints the version and exits.
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 PHPUnit2_Framework_TestCase
or a class that
provides a public static suite()
method which
returns an PHPUnit2_Framework_Test
object, for
example an instance of the
PHPUnit2_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.
--coverage-data
, --coverage-html
, and --coverage-text
Control the collection and analysis of Code Coverage information for the tests that are run. (See Chapter 9.)
--testdox-html
and --testdox-text
Generates agile documentation in HTML or plain text format for the tests that are run. (See Chapter 11.)
--log-xml
Generates a logfile in XML format for the tests run.
The following example shows the XML logfile generated for the tests
in ArrayTest
:
<?xml version="1.0" encoding="UTF-8"?> <testsuites> <testsuite name="ArrayTest" tests="2" failures="0" errors="0" time="0.020026"> <testcase name="testNewArrayIsEmpty" class="ArrayTest" time="0.014449"/> <testcase name="testArrayContainsAnElement" class="ArrayTest" time="0.005577"/> </testsuite> </testsuites>
This XML logfile was generated for two tests,
testFailure
and testError
,
of a test-case class named FailureErrorTest
and
shows how failures and errors are denoted.
<?xml version="1.0" encoding="UTF-8"?> <testsuites> <testsuite name="FailureErrorTest" tests="2" failures="1" errors="1" time="0.013603"> <testcase name="testFailure" class="FailureErrorTest" time="0.011872"> <failure message="" type="PHPUnit2_Framework_AssertionFailedError"></failure> </testcase> <testcase name="testError" class="FailureErrorTest" time="0.001731"> <error message="" type="Exception"></error> </testcase> </testsuite> </testsuites>
--loader
Specifies the PHPUnit2_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
.
--skeleton
Generates a skeleton test-case class UnitTest
(in UnitTest.php
) for a class
Unit
(in Unit.php
).
For each method in the original class, there will be an incomplete
test-case (see Chapter 7) in the generated
test-case class.
The following example shows how to generate a a skeleton test class
for a class named Sample
.
phpunit --skeleton Sample
PHPUnit 2.3.0 by Sebastian Bergmann. Wrote test class skeleton for Sample to SampleTest.php.phpunit SampleTest
PHPUnit 2.3.0 by Sebastian Bergmann. I Time: 0.007268 There was 1 incomplete test case: 1) testSampleMethod(SampleTest) OK, but incomplete test cases!!! Tests run: 1, incomplete test cases: 1.
When you are writing tests for existing code, you have to write the same code fragments as in the following example:
public function testSampleMethod() {
}
over and over again. PHPUnit can help you by analyzing the existing code and generating a skeleton test-case class for it.
--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.
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. Future versions of PHPUnit will solve this issue by using a sandboxed PHP interpreter.