Phpunit coverage: what is the difference between 'addUncoveredFilesFromWhitelist' and 'processUncoveredFilesFromWhitelist' options?

Question

I'm trying to set up code coverage for phpunit for a particular directory. Can someone tell me what is the difference between:

<filter>
    <whitelist>
        <directory suffix=".php">lib/</directory>
    </whitelist>
</filter>

and

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

and

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

Currently the first 2 options will work (with different coverage numbers) but the third one will fail with errors similar to How to add uncovered files to PHPUnit code coverage report of the Yii application.

Just starting out with phpunit and would like to understand the differences between these whitelisting options. I read the official docs on this but I'm not sure I understand.

Answer 1

A quick peek in the source code of php-code-coverage package on GitHub reveals the truth:

• if addUncoveredFilesFromWhitelist is FALSE then the code coverage contains information about the files that were loaded and executed (only the lines that contain code are included);
  the value of processUncoveredFilesFromWhitelist is ignored in this case;
• if addUncoveredFilesFromWhitelist is TRUE then the files from the white list that were not loaded and executed will be included in the code coverage too:
  • if processUncoveredFilesFromWhitelist is FALSE then the files are not processed in any way; all their lines will appear in the code coverage as not being executed, even the empty lines and the lines that contain only comments; this is the quick and dirty way to get the things done;
  • if processUncoveredFilesFromWhitelist is TRUE then the files are included and XDebug's code coverage functionality is used (the same as for the files that actually ran) to put into the report only the lines that contain code; this is the slow hard-working way.

The default value for addUncoveredFilesFromWhitelist is TRUE and for processUncoveredFilesFromWhitelist is FALSE. This means the files from the whitelist that were not covered (because they didn't run) are included in the report using the quick way and their coverage report, while exact (0%), is computed using a total number of rows slightly bigger than the real one.

However, since 0 out of anything is still 0%, it think this is the best way to include the uncovered files in the report.

Answer 2

So I think I was wrong. Here's what the documentation has to say about it:

Optionally, all whitelisted files can be added to the code coverage report by setting addUncoveredFilesFromWhitelist="true" in your PHPUnit configuration (see the section called “Including and Excluding Files for Code Coverage”). This allows the inclusion of files that are not tested yet at all. If you want to get information about which lines of such an uncovered file are executable, for instance, you also need to set processUncoveredFilesFromWhitelist="true" in your PHPUnit configuration (see the section called “Including and Excluding Files for Code Coverage”).

So the answer here is that adding the uncovered files will include them in the coverage report, but actually processing them will gather further information.

Original

See this twitter conversation from Sebastian. It's a little hard to tell from twitter's terseness, but it looks like addUncoveredFilesFromWhitelist may just be an older form of the same functionality that processUncoveredFilesFromWhitelist provides for legacy code.

The content of the twitter conversation is:

@user1: In @phpunit, what’s the difference between addUncoveredFilesFromWhitelist="true" and processUncoveredFilesFromWhitelist="true" ?

@s_bergmann: You want to use processUncoveredFilesFromWhitelist. If it does not work (legacy code) then use addUncoveredFilesFromWhitelist