sebastianbergmann/php-code-coverage — pull request #240 by julianseeger (2014-04-27 15:47:35+00:00)
Title: Fix merging of PHP coverage reports

2.0 Version of #239
>2.0 is for bug fixes only. As your patch changes the API in a BC-friendly way it could be merged there. And the case could be made that this change is a bug fix.

### What does this PR?
It allows the PHP Reporter to export the "raw" coverage by addind the $raw parameter to CodeCoverage::getData. This means the reporter will get the coverage as it is in the $data attribute of the CodeCoverage without "addUncoveredFilesFromWhitelist()" applied.
This behavior equals the behavior of php-code-coverage 1 where the coverage has just been serialized (and thus also not been modified).

### Why is this important?
***TL;DR:***
The combination of ```PHP_CodeCoverage_Report_PHP```, ```addUncoveredFilesFromWhitelist``` and ```PHP_CodeCoverage::merge``` is broken.

***Long version:***
The method addUncoveredFilesFromWhitelist also adds lines as uncovered that whouldn't show up when the file had coverage. The result is this bad behavior:

Given you have two tests, Test1 and Test2, and a File1 with source.
Test1:
```PHP
...
public function testNothing()
{
$this->assertTrue(true);
}
...
```

Test2:
````PHP
...
public function testFile1()
{
$sut = new File1();
$this->assertTrue($sut->giveMeTrue());
}
...
```

File1:
```PHP
class File1
{
public function giveMeTrue()
{
return true;
}
}
```

Test1 does not cover any line of File1 but Test2 covers File1 fully.
Given File1 is in the whitelist for uncovered files.
When you execute only Test1 with ```--coverage-php coverage1.php``` and after that only Test2 with ```--coverage-php coverage2.php```, then both reports will contain information for File1, but coverage1.php will mark line 4-6 as uncovered (the opening curly brace, the return and the closing curly brace) and coverage1.php will mark only line 5-6 as covered (only the return and the closing curly brace).

So when you now merge coverage1.php and coverage2.php, the result will be that line 4 is uncovered, line 5 is covered and line 6 is covered. Incorrect information just because the data was modified before exporting it.

Merge Result:
```PHP
public function giveMeTrue()
{ // uncovered
return true; // covered
} // covered
```

### Real world example
Paratest is a project, where the tests are executed in separation for each TestCase. The coverage is exported as php and after every TestCase has been executed, the coverage for each test is loaded and merged. The result is (since phpunit4) that many curly braces are marked as uncovered and the coverage information after the merge is pretty useless.
For details, take a look at https://github.com/brianium/paratest/issues/89