C.59 PHPUnitTask
Prev | Appendix C. Optional tasks | Next

## C.59 PHPUnitTask

This task runs testcases using the PHPUnit framework. It is a functional port of the Ant JUnit task.

NB: if you have installed the PHPUnit PHAR, make sure you set the `pharlocation` attribute!

NB: the identifiers `phpunit2` (PHPUnit2Task) and `phpunit3` (PHPUnit3Task) have been deprecated!

Table C.83: Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
`printsummary` | `Boolean` | Print one-line statistics for each testcase. | `false` | No
`bootstrap` | `String` | The name of a bootstrap file that is run before executing the tests. | none | No
`codecoverage` | `Boolean` | Gather code coverage information while running tests (requires Xdebug). | `false` | No
`haltonerror` | `Boolean` | Stop the build process if an error occurs during the test run. | `false` | No
`haltonfailure` | `Boolean` | Stop the build process if a test fails (errors are considered failures as well). | `false` | No
`haltonincomplete` | `Boolean` | Stop the build process if any incomplete tests are encountered. | `false` | No
`haltonskipped` | `Boolean` | Stop the build process if any skipped tests are encountered. | `false` | No
`failureproperty` | `String` | Name of property to set (to true) on failure. | n/a | No
`errorproperty` | `String` | Name of property to set (to true) on error. | n/a | No
`incompleteproperty` | `String` | Name of property to set (to true) on incomplete tests. | n/a | No
`skippedproperty` | `String` | Name of property to set (to true) on skipped tests. | n/a | No
`usecustomerrorhandler` | `Boolean` | Use a custom Phing/PHPUnit error handler to process PHP errors. | `true` | No
`processisolation` | `Boolean` | Enable process isolation when executing tests. | `false` | No
`configuration` | `String` | Path to a PHPUnit configuration file (such as `phpunit.xml`). Supported elements are: `bootstrap`, `processIsolation`, `stopOnFailure`, `stopOnError`, `stopOnIncomplete` and `stopOnSkipped`. Values provided overwrite other attributes! | n/a | No
`groups` | `String` | Only run tests from the specified group(s). | n/a | No
`excludeGroups` | `String` | Exclude tests from the specified group(s). | n/a | No
`pharlocation` | `String` | Location of the PHPUnit PHAR package. | n/a | No

### C.59.1 Supported Nested Tags

- `formatter`

  The results of the tests can be printed in different formats. Output will always be sent to a file, unless you set the `usefile` attribute to `false`. The name of the file is predetermined by the formatter and can be changed by the `outfile` attribute.

  There are three predefined formatters - `xml` and `clover` print the test results in the JUnit and Clover XML formats, the `plain` formatter emits a short statistics line for all test cases. Custom formatters that implement phing.tasks.ext.phpunit.formatter.PHPUnitResultFormatter can be specified.

  Table C.84: Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  `type` | `String` | Use a predefined formatter (either `xml`, `plain`, `clover`, or `summary`). | n/a | One of these is required.
  `classname` | `String` | Name of a custom formatter class. | n/a
  `usefile` | `Boolean` | Boolean that determines whether output should be sent to a file. | `true` | No
  `todir` | `String` | Directory to write the file to. | n/a | No
  `outfile` | `String` | Filename of the result. | Depends on formatter | No

- `batchtest`

  Define a number of tests based on pattern matching. `batchtest` collects the included files from any number of nested <fileset>s. It then generates a lists of classes that are (in)directly defined by each PHP file.

  Table C.85: Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  `exclude` | `String` | A list of classes to exclude from the pattern matching. For example, when you have two baseclasses `BaseWebTest` and `BaseMathTest`, which are included a number of testcases (and thus added to the list of testclasses), you can exclude those classes from the list by typing `exclude="BaseWebTest BaseMathTest"`. | n/a | No
  `classpath` | `String` | Used to define more paths on which - besides the PHP include_path - to look for the test files. | n/a | No
  `name` | `String` | The name that is used to create a testsuite from this batchtest. | Phing Batchtest | No

### C.59.2 Example

    <phpunit>
      <formatter todir="reports" type="xml"/>
      <batchtest>
        <fileset dir="tests">
          <include name="**/*Test*.php"/>
          <exclude name="**/Abstract*.php"/>
        </fileset>
      </batchtest>
    </phpunit>

Runs all matching testcases in the directory `tests`, writing XML results to the directory `reports`.

    <phpunit codecoverage="true" haltonfailure="true" haltonerror="true">
      <formatter type="plain" usefile="false"/>
      <batchtest>
        <fileset dir="tests">
          <include name="**/*Test*.php"/>
        </fileset>
      </batchtest>
    </phpunit>

Runs all matching testcases in the directory `tests`, gathers code coverage information, writing plain text results to the console. The build process is aborted if a test fails.

    <phpunit bootstrap="src/autoload.php">
      <formatter type="plain" usefile="false"/>
      <batchtest>
        <fileset dir="tests">
          <include name="**/*Test*.php"/>
        </fileset>
      </batchtest>
    </phpunit>

Runs all matching testcases in the directory `tests`, writing plain text results to the console. Additionally, before executing the tests, the bootstrap file `src/autoload.php` is loaded.

Important note: using a mechanism such as an "AllTests.php" file to execute testcases will bypass the Phing hooks used for reporting and counting, and could possibly lead to strange results. Instead, use one of more fileset's to provide a list of testcases to execute.

### C.59.3 Supported Nested Tags

- `fileset`

Prev | Up | Next
C.58 PhpLintTask | Home | C.60 PHPUnitReport