Prev Next

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.5.0 by Sebastian Bergmann.

..

Time: 0 seconds


OK (2 tests, 2 assertions)

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.5.0 by Sebastian Bergmann.

Usage: phpunit [switches] UnitTest [UnitTest.php]
       phpunit [switches] <directory>

  --log-junit <file>       Log test execution in JUnit XML format to file.
  --log-tap <file>         Log test execution in TAP format to file.
  --log-dbus               Log test execution to DBUS.
  --log-json <file>        Log test execution in JSON format.

  --coverage-html <dir>    Generate code coverage report in HTML format.
  --coverage-clover <file> Write code coverage data in Clover XML format.

  --story-html <file>      Write Story/BDD results in HTML format to file.
  --story-text <file>      Write Story/BDD results 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.

  --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).
  --list-groups            List available test groups.

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

  --story                  Report test execution progress in Story/BDD format.
  --tap                    Report test execution progress in TAP format.
  --testdox                Report test execution progress in TestDox format.

  --colors                 Use colors in output.
  --stderr                 Write to STDERR instead of STDOUT.
  --stop-on-error          Stop execution upon first error.
  --stop-on-failure        Stop execution upon first error or failure.
  --stop-on-skipped        Stop execution upon first skipped test.
  --stop-on-incomplete     Stop execution upon first incomplete test.
  --strict                 Mark a test as incomplete if no assertions are made.
  --verbose                Output more verbose information.
  --wait                   Waits for a keystroke after each test.

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

  --process-isolation      Run each test in a separate PHP process.
  --no-globals-backup      Do not backup and restore $GLOBALS for each test.
  --static-backup          Backup and restore static attributes for each test.
  --syntax-check           Try to check source files for syntax errors.

  --bootstrap <file>       A "bootstrap" PHP file that is run before the tests.
  --configuration <file>   Read configuration from XML file.
  --no-configuration       Ignore default configuration file (phpunit.xml).
  --include-path <path(s)> Prepend PHP's include_path with given path(s).
  -d key[=value]           Sets a php.ini value.

  --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 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-junit

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

--log-tap

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

--log-dbus

Log test execution using DBUS.

--log-json

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

--coverage-html

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

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

--coverage-clover

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

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

--story-html and --story-text

Generates reports in HTML or plain text format for the Behaviour-Driven Development scenarios that are run. See ??? for more details.

--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.

The @author annotation is an alias for @group allowing to filter tests based on their authors.

--exclude-group

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

--list-groups

List available test groups.

--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.

--story

Reports the test progress in a format that fits Behaviour-Driven Development. See ??? for more details.

--tap

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

--testdox

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

--colors

Use colors in output.

--stderr

Optionally print to STDERR instead of STDOUT.

--stop-on-error

Stop execution upon first error.

--stop-on-failure

Stop execution upon first error or failure.

--stop-on-skipped

Stop execution upon first skipped test.

--stop-on-skipped

Stop execution upon first incomplete test.

--strict

Mark a test as incomplete if no assertions are made.

--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-class

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

--skeleton-test

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

--process-isolation

Run each test in a separate PHP process.

--no-globals-backup

Do not backup and restore $GLOBALS. See the section called “Global State” for more details.

--static-backup

Backup and restore static attributes of user-defined classes. See the section called “Global State” for more details.

--syntax-check

Enables the syntax check of test source files.

--bootstrap

A "bootstrap" PHP file that is run before the tests.

--configuration, -c

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

If phpunit.xml or phpunit.xml.dist (in that order) exist in the current working directory and --configuration is not used, the configuration will be automatically read from that file.

--no-configuration

Ignore phpunit.xml and phpunit.xml.dist from the current working directory.

--include-path

Prepend PHP's include_path with given path(s).

-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 can optionally check the test suite sourcefile for PHP syntax errors, but not sourcefiles included by the test suite sourcefile.

Prev Next
1. Automating Tests
2. PHPUnit's Goals
3. Installing PHPUnit
4. Writing Tests for PHPUnit
Test Dependencies
Data Providers
Testing Exceptions
Testing PHP Errors
5. The Command-Line Test Runner
6. Fixtures
More setUp() than tearDown()
Variations
Sharing Fixture
Global State
7. Organizing Tests
Composing a Test Suite Using the Filesystem
Composing a Test Suite Using XML Configuration
Using the TestSuite Class
8. TestCase Extensions
Testing Output
9. Database Testing
Data Sets
Flat XML Data Set
XML Data Set
CSV Data Set
Replacement Data Set
Operations
Database Testing Best Practices
10. Incomplete and Skipped Tests
Incomplete Tests
Skipping Tests
11. Test Doubles
Stubs
Mock Objects
Stubbing and Mocking Web Services
Mocking the Filesystem
12. Testing Practices
During Development
During Debugging
13. Test-Driven Development
BankAccount Example
14. Code Coverage Analysis
Specifying Covered Methods
Ignoring Code Blocks
Including and Excluding Files
15. Other Uses for Tests
Agile Documentation
Cross-Team Tests
16. Skeleton Generator
Generating a Test Case Class Skeleton
Generating a Class Skeleton from a Test Case Class
17. PHPUnit and Selenium
Selenium RC
PHPUnit_Extensions_SeleniumTestCase
18. Logging
Test Results (XML)
Test Results (TAP)
Test Results (JSON)
Code Coverage (XML)
19. Build Automation
Apache Ant
Apache Maven
Phing
20. Continuous Integration
Atlassian Bamboo
CruiseControl
phpUnderControl
21. PHPUnit API
Overview
PHPUnit_Framework_Assert
assertArrayHasKey()
assertClassHasAttribute()
assertClassHasStaticAttribute()
assertContains()
assertContainsOnly()
assertEmpty()
assertEqualXMLStructure()
assertEquals()
assertFalse()
assertFileEquals()
assertFileExists()
assertGreaterThan()
assertGreaterThanOrEqual()
assertInstanceOf()
assertInternalType()
assertLessThan()
assertLessThanOrEqual()
assertNull()
assertObjectHasAttribute()
assertRegExp()
assertStringMatchesFormat()
assertStringMatchesFormatFile()
assertSame()
assertSelectCount()
assertSelectEquals()
assertSelectRegExp()
assertStringEndsWith()
assertStringEqualsFile()
assertStringStartsWith()
assertTag()
assertThat()
assertTrue()
assertType()
assertXmlFileEqualsXmlFile()
assertXmlStringEqualsXmlFile()
assertXmlStringEqualsXmlString()
PHPUnit_Framework_Test
PHPUnit_Framework_TestCase
PHPUnit_Framework_TestSuite
PHPUnit_Framework_TestResult
Package Structure
22. Extending PHPUnit
Subclass PHPUnit_Framework_TestCase
Assert Classes
Subclass PHPUnit_Extensions_TestDecorator
Implement PHPUnit_Framework_Test
Subclass PHPUnit_Framework_TestResult
Implement PHPUnit_Framework_TestListener
New Test Runner
A. Assertions
B. Annotations
@assert
@author
@backupGlobals
@backupStaticAttributes
@covers
@dataProvider
@depends
@expectedException
@expectedExceptionCode
@expectedExceptionMessage
@group
@outputBuffering
@runTestsInSeparateProcesses
@runInSeparateProcess
@test
@testdox
@ticket
C. The XML Configuration File
PHPUnit
Test Suites
Groups
Including and Excluding Files for Code Coverage
Logging
Test Listeners
Setting PHP INI settings, Constants and Global Variables
Configuring Browsers for Selenium RC
D. Index
E. Bibliography
F. Copyright