C.59 PHPUnitTask

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

NB: if you want to use the PHPUnit .phar file, please make sure you download the library version (phpunit-library.phar) and you set the pharlocation attribute!

Table C.77: Attributes

NameTypeDescriptionDefaultRequired
printsummaryBooleanPrint one-line statistics for each testcase.falseNo
bootstrapStringThe name of a bootstrap file that is run before executing the tests.noneNo
codecoverageBooleanGather code coverage information while running tests (requires Xdebug).falseNo
haltonerrorBooleanStop the build process if an error occurs during the test run.falseNo
haltonfailureBooleanStop the build process if a test fails (errors are considered failures as well).falseNo
haltondefectBooleanStop the build process if a test has failures, errors or warnings.falseNo
haltonincompleteBooleanStop the build process if any incomplete tests are encountered.falseNo
haltonskippedBooleanStop the build process if any skipped tests are encountered.falseNo
haltonwarningBooleanStop the build process if any warnings are encountered.falseNo
haltonriskyBooleanStop the build process if any risky tests are encountered.falseNo
failurepropertyStringName of property to set (to true) on failure.n/aNo
errorpropertyStringName of property to set (to true) on error.n/aNo
incompletepropertyStringName of property to set (to true) on incomplete tests.n/aNo
skippedpropertyStringName of property to set (to true) on skipped tests.n/aNo
warningpropertyStringName of property to set (to true) on warnings.n/aNo
riskypropertyStringName of property to set (to true) on risky tests.n/aNo
usecustomerrorhandlerBooleanUse a custom Phing/PHPUnit error handler to process PHP errors.trueNo
processisolationBooleanEnable process isolation when executing tests.falseNo
configurationStringPath 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/aNo
groupsStringOnly run tests from the specified group(s).n/aNo
excludeGroupsStringExclude tests from the specified group(s).n/aNo
pharlocationStringLocation of the PHPUnit PHAR package.n/aNo

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 six predefined formatters. xml, clover, and crap4j print the test results in the JUnit, Clover, and Crap4J XML formats respectively. The clover-html formatter prints code coverage details to a set of HTML files. The plain formatter emits a short statistics line for all test cases. The summary formatter print the same statistics as the plain formatter but only to the log output. Custom formatters that implement Phing\Task\Ext\Formatter\PHPUnitResultFormatter can be specified.

    Table C.78: Attributes

    NameTypeDescriptionDefaultRequired
    typeStringUse a predefined formatter (either xml, plain, clover, clover-html, crap4j, or summary). n/aOne of these is required.
    classnameStringName of a custom formatter class.n/a
    usefileBooleanBoolean that determines whether output should be sent to a file.trueNo
    todirStringDirectory to write the file to.n/aNo
    outfileStringFilename of the result.Depends on formatterNo

  • 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.79: Attributes

    NameTypeDescriptionDefaultRequired
    excludeStringA 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/aNo
    classpathStringUsed to define more paths on which - besides the PHP include_path - to look for the test files.n/aNo
    nameStringThe name that is used to create a testsuite from this batchtest.Phing BatchtestNo

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