php - 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.