Introduce <source> XML configuration element to configure "your code"

[sebastianbergmann]

Status Quo

The XML configuration file can already be used to specify which code you are interested in when it comes to code coverage reporting:

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

The configuration shown above limits the code coverage reporting to *.php files in the src directory. Code that is executed while the tests are run that is declared in source code files outside of src, vendor, for instance, are not included in code coverage reports.

Motivation

As of PHPUnit 10.0, the test runner prints D, N, and W, respectively, for tests that execute code which triggers E_DEPRECATED, E_USER_DEPRECATED, E_NOTICE, E_USER_NOTICE, E_STRICT, E_WARNING, or E_USER_WARNING events. Detailed information (which notices was triggered where, for instance) is only printed when --display-deprecations, --display-notices, or --display-warnings is used.

The test runner should support limiting the reporting of deprecations, notices, and warnings to "your code", excluding code from directories such as vendor, for example. This is covered in #5293.

Proposal

In order to limit the reporting of deprecations, notices, and warnings to source code files in specified directories, this information needs to be put into the XML configuration file.

I do not think it makes sense to have two separate configuration elements for configuring the source code you are interested in: one for code coverage and another for the reporting of deprecations, notices, and warnings.

I therefore propose the following:

Step 1

Introduce a new <source> element for the XML configuration file:

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

<source> will be used for limiting the reporting of deprecations, notices, and warnings to the specified directories and files.

When <source> is present and <coverage> is absent then <source> will be used instead of <coverage> for code coverage filtering.

When both <source> and <coverage> are present then <coverage> will be used for code coverage filtering.

Step 2 (in the same version as Step 1)

Deprecate using <include> and <exclude> (and their children <directory> and <file>) under <coverage> to configure code coverage filtering.

Implement XML configuration file migrator to migrate from <coverage> to <source> to configure code coverage filtering.

Step 3 (in the same version as Step 1)

Change --generate-configuration to generate a phpunit.xml file that uses <source> instead of <coverage> to configure code coverage filtering.

Step 4 (in the next major version after previous steps)

Remove support for using <include> and <exclude> (and their children <directory> and <file>) under <coverage> to configure code coverage filtering.

[Slamdunk]

Hi, I'm currently on 07c279b and my suite is warning me with:

There was 1 PHPUnit test runner warning:

1) Test results may not be as expected because the XML configuration file did not pass validation:

  Line 14:
  - Element 'include': This element is not expected.

But I can't find the proper way to adapt the XML to the new required XSD.
The migration tool doesn't seem to be helpful either:

$ vendor/bin/phpunit --migrate-configuration
PHPUnit 10.1-dev by Sebastian Bergmann and contributors.

Created backup:         ./phpunit.xml.bak
Migration failed: "./phpunit.xml" is not a valid PHPUnit XML configuration file that can be migrated

Could be the changelog for 10.1 updated with some more details please?