Skip to content

Latest commit

 

History

History
167 lines (133 loc) · 12.4 KB

ChangeLog-9.3.md

File metadata and controls

167 lines (133 loc) · 12.4 KB
Raw

Changes in PHPUnit 9.3

All notable changes of the PHPUnit 9.3 release series are documented in this file using the Keep a CHANGELOG principles.

9.3.0 - 2020-08-07

Added

  • #3936: Support using @depends to depend on classes
  • #4260: pathCoverage attribute on the phpunit/coverage element of the XML configuration file for enabling path coverage for code coverage drivers that support it
  • #4288: Add option for migrating phpunit.xml from a supported but outdated XML schema version
  • #4314: Add option to exit with exit code 1 when no tests are executed
  • #4325: Support PHP 8
  • #4365: assertIsClosedResource() and assertIsNotClosedResource()
  • --path-coverage CLI option for enabling path coverage for code coverage drivers that support it

Changed

  • #4226: Deprecate --dump-xdebug-filter and --prepend
  • #4264: Refactor logical operator constraints
  • #4365: assertIsResource() and assertIsNotResource() now handle closed resources
  • PHPUnit\Framework\TestCase::$backupGlobalsBlacklist is now deprecated, please use PHPUnit\Framework\TestCase::$backupGlobalsExcludeList instead
  • PHPUnit\Framework\TestCase::$backupStaticAttributesBlacklist is now deprecated, please use PHPUnit\Framework\TestCase::$backupStaticAttributesExcludeList instead
  • PHPUnit\Util\Blacklist is now deprecated, please use PHPUnit\Util\ExcludeList instead
  • Using --whitelist <directory> to include a directory in code coverage reports is now deprecated, please use --coverage-filter <directory> instead
  • Using --generate-configuration now generates a configuration file with failOnRisky="true" and failOnWarning="true"

Configuration of Code Coverage and Logging in phpunit.xml

The configuration of code coverage and logging in phpunit.xml has been changed to be less confusing. Here is an example of what this configuration looked like prior to PHPUnit 9.3:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.2/phpunit.xsd"
         cacheTokens="true"
         disableCodeCoverageIgnore="true"
         ignoreDeprecatedCodeUnitsFromCodeCoverage="true">
    <!-- ... -->

    <filter>
        <whitelist addUncoveredFilesFromWhitelist="true"
                   processUncoveredFilesFromWhitelist="true">
            <directory suffix=".php">src</directory>

            <exclude>
                <directory suffix=".php">src/generated</directory>
                <file>src/autoload.php</file>
            </exclude>
        </whitelist>
    </filter>

    <logging>
        <log type="coverage-html" target="html-coverage" lowUpperBound="50" highLowerBound="90"/>
        <log type="coverage-clover" target="clover.xml"/>
        <log type="coverage-crap4j" threshold="50" target="crap4j.xml"/>
        <log type="coverage-text" showUncoveredFiles="false" showOnlySummary="true" target="coverage.txt"/>
        <log type="junit" target="junit.xml"/>
        <log type="teamcity" target="teamcity.txt"/>
        <log type="testdox-html" target="testdox.html"/>
        <log type="testdox-text" target="testdox.txt"/>
        <log type="testdox-xml" target="testdox.xml"/>
        <log type="plain" target="logfile.txt"/>
    </logging>
</phpunit>

A long time ago, PHPUnit supported both an exclude-list ("blacklist"), and an include-list ("whitelist") for filter files for code coverage. Back then, the exclude-list was pre-filled with PHPUnit's own sourcecode files as well as the sourcecode files of its dependencies. When the (back then) optional include-list was configured, the exclude-list was ignored and only the files on the include-list were considered for code coverage. This was confusing, and the exclude-list was removed long ago, but the <filter><whitelist> structure was not simplified at the time although it was no longer necessary.

For lack of better terminology, an XML element such as <log type="coverage-html" target="/path/to/directory"/> is an implicit API that is not type-safe. It is neither obvious that coverage-html is a valid value for type nor is it obvious that the value of target needs to be a directory.

Some configuration options for code coverage were represented as attributes on the root <phpunit> element while others were represented as attributes on the <whitelist> element.

Here is what the same configuration looks like in PHPUnit 9.3:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
    <!-- ... -->

    <coverage includeUncoveredFiles="true"
              processUncoveredFiles="true"
              ignoreDeprecatedCodeUnits="true"
              disableCodeCoverageIgnore="true">
        <include>
            <directory suffix=".php">src</directory>
        </include>

        <exclude>
            <directory suffix=".php">src/generated</directory>
            <file>src/autoload.php</file>
        </exclude>

        <report>
            <clover outputFile="clover.xml"/>
            <crap4j outputFile="crap4j.xml" threshold="50"/>
            <html outputDirectory="html-coverage" lowUpperBound="50" highLowerBound="90"/>
            <php outputFile="coverage.php"/>
            <text outputFile="coverage.txt" showUncoveredFiles="false" showOnlySummary="true"/>
            <xml outputDirectory="xml-coverage"/>
        </report>
    </coverage>

    <logging>
        <junit outputFile="junit.xml"/>
        <teamcity outputFile="teamcity.txt"/>
        <testdoxHtml outputFile="testdox.html"/>
        <testdoxText outputFile="testdox.txt"/>
        <testdoxXml outputFile="testdox.xml"/>
        <text outputFile="logfile.txt"/>
    </logging>
</phpunit>

In the example shown above, the section

<include>
    <directory suffix=".php">src</directory>
</include>

<exclude>
    <directory suffix=".php">src/generated</directory>
    <file>src/autoload.php</file>
</exclude>

configures the following:

  • Include all files with .php suffix in the src directory and its sub-directories in the code coverage report
  • But exclude all files with .php suffix in the src/generated directory and its sub-directories as well as the src/autoload.php file from the code coverage report

We believe this new way of configuring code coverage and logging in phpunit.xml to be more clear for the users. We already know that the code that parses phpunit.xml is now more robust than it was before. We also know that adding support for the configuration of more advanced code coverage options such as path coverage would have made the confusion even worse.

A phpunit.xml configuration file that was valid (according to phpunit.xsd) for PHPUnit 9.2 will continue to work with PHPUnit 9.3. However, PHPUnit 9.3 will complain about validation errors when it loads the phpunit.xml configuration file.

Here is a detailed list of changes for the configuration of code coverage and logging in phpunit.xml:

  • Using <filter><whitelist><include>...</include></whitelist></filter to include a directory in code coverage reports is now deprecated, please use <coverage><include>...</include></coverage> instead
  • Using <filter><whitelist><exclude>...</exclude></whitelist></filter to exclude a directory from code coverage reports is now deprecated, please use <coverage><exclude>...</exclude></coverage> instead
  • Using <filter><whitelist addUncoveredFilesFromWhitelist="false">...</whitelist></filter> to control whether or not uncovered files should be added to code coverage reports is now deprecated, please use <coverage includeUncoveredFiles="false">...</coverage> instead
  • Using <filter><whitelist processUncoveredFilesFromWhitelist="true">...</whitelist></filter> to control whether or not uncovered files should be processed for code coverage reporting is now deprecated, please use <coverage processUncoveredFiles="true">...</coverage> instead
  • Using <phpunit disableCodeCoverageIgnore="true">...</phpunit> to configure whether @coverCoverageIgnore annotations should be ignored is now deprecated, please use <phpunit><coverage disableCodeCoverageIgnore="true">...</coverage></phpunit> instead
  • Using <phpunit ignoreDeprecatedCodeUnitsFromCodeCoverage="true">...</phpunit> to configure whether code units annotated with @deprecated should be ignored is now deprecated, please use <phpunit><coverage ignoreDeprecatedCodeUnits="true">...</coverage></phpunit> instead
  • Using <logging><log type="coverage-clover" target="clover.xml"/></logging> to configure the Clover XML code coverage report is now deprecated, please use <coverage><report><clover outputFile="clover.xml"/></report></coverage> instead
  • Using <logging><log type="coverage-crap4j" target="crap4j.xml" threshold="50"/></logging> to configure the Crap4J XML code coverage report is now deprecated, please use <coverage><report><crap4j outputFile="crap4j.xml" threshold="50"/></report></coverage> instead
  • Using <logging><log type="coverage-html" target="coverage" lowUpperBound="50" highLowerBound="90"/></logging> to configure the HTML code coverage report is now deprecated, please use <coverage><report><html outputDirectory="coverage" lowUpperBound="50" highLowerBound="90"/></report></coverage> instead
  • Using <logging><log type="coverage-php" target="coverage.php"/></logging> to configure the PHP code coverage report is now deprecated, please use <coverage><report><php outputFile="coverage.php"/></report></coverage> instead
  • Using <logging><log type="coverage-text" target="coverage.txt" showUncoveredFiles="false" showOnlySummary="true"/></logging> to configure the Text code coverage report is now deprecated, please use <coverage><report><text outputFile="coverage.txt" showUncoveredFiles="false" showOnlySummary="true"/></report></coverage> instead
  • Using <logging><log type="coverage-xml" target="coverage"/></logging> to configure the XML code coverage report is now deprecated, please use <coverage><report><xml outputDirectory="coverage"/></report></coverage> instead
  • Using <logging><log type="junit" target="junit.xml"/></logging> to configure the JUnit XML logger is now deprecated, please use <logging><junit outputFile="junit.xml"/></logging> instead
  • Using <logging><log type="teamcity" target="teamcity.txt"/></logging> to configure the TeamCity logger is now deprecated, please use <logging><teamcity outputFile="teamcity.txt"/></logging> instead
  • Using <logging><log type="testdox-html" target="testdox.html"/></logging> to configure the TestDox HTML logger is now deprecated, please use <logging><testdoxHtml outputFile="testdox.html"/></logging> instead
  • Using <logging><log type="testdox-text" target="testdox.txt"/></logging> to configure the TestDox Text logger is now deprecated, please use <logging><testdoxText outputFile="testdox.txt"/></logging> instead
  • Using <logging><log type="testdox-xml" target="testdox.xml"/></logging> to configure the TestDox XML logger is now deprecated, please use <logging><testdoxXml outputFile="testdox.xml"/></logging> instead
  • Using <logging><log type="plain" target="logfile.txt"/></logging> to configure the plain text logger is now deprecated, please use <logging><text outputFile="logfile.txt"/></logging> instead

If you have an XML configuration file that validates against PHPUnit 9.2's XML schema, then you can use the new --migrate-configuration CLI option to automatically migrate your XML configuration file to the new format.

Removed

  • #4297: Deprecate at() matcher
  • #4396: Deprecate confusing parameter options for XML assertions
  • The cacheTokens attribute is no longer supported in XML configuration files