#Test Coverage

Note: Generating code coverage requires XDebug 3.0+ or PCOV.

Test coverage (or code coverage) is a metric used to measure the percentage of code that is executed during testing. This helps you identify the parts of your code that may not be tested, or that have low coverage, indicating a potential risk for bugs and other issues.

Typically, the essential configuration for gathering code coverage is already present in the phpunit.xml file provided by frameworks, or is generated by executing the ./vendor/bin/pest --init command. If code coverage configuration is not present in your phpunit.xml file, you may add your own configuration to specify the paths in your project that should receive code coverage reporting:

1...
2<source>
3    <include>
4        <directory suffix=".php">./app</directory>
5    </include>
6</source>
7...

In addition to configuring your phpunit.xml file, you will also need to install XDebug 3.0+ or PCOV to generate a code coverage report. When utilizing XDebug, the XDEBUG_MODE environment variable must be configured as coverage.

Once you have configured your code coverage settings and installed a coverage driver, generating a code coverage report becomes painless with the use of the --coverage option:

1./vendor/bin/pest --coverage

When you use the --coverage option, the test suite runs normally, but with the added benefit of displaying a list of your project files and their corresponding coverage results:

If there are any uncovered lines in your current test suite, they will be highlighted in red and displayed using their respective line numbers. Multiple uncovered lines will be displayed with two dots (..) between them. For instance, if there is missing coverage between lines 52 and 60, you will see 52..60 in red, rather than a single line number.

#Minimum Threshold Enforcement

To ensure comprehensive testing and maintain code quality, it is helpful to set minimum threshold values for coverage results. In Pest, you may use the --coverage option together with --min or --exactly to define the minimum threshold values for coverage results. If the specified thresholds are not met, Pest will report a failure:

1./vendor/bin/pest --coverage --min=90

Alternatively, you may use the --exactly option to enforce that the coverage results match the specified value exactly:

1./vendor/bin/pest --coverage --exactly=99.3

#Hiding Uncovered Files

When working on a large codebase, the coverage report may become noisy with many files showing 0% coverage. You may use the --only-covered option to hide files with no coverage from the report, allowing you to focus on the files that are partially covered:

1./vendor/bin/pest --coverage --only-covered

This option may be combined with --min or --exactly for threshold enforcement:

1./vendor/bin/pest --coverage --only-covered --min=90

#Ignoring Code

Sometimes there are certain sections of your application that cannot be tested and should be excluded from code coverage analysis. To accomplish this, you may use @codeCoverageIgnoreStart and @codeCoverageIgnoreEnd comments in your source code:

1// @codeCoverageIgnoreStart
2function getUsers() {
3    //
4}
5// @codeCoverageIgnoreEnd

#Different Formats

Pest supports a variety of code coverage report formats:

• --coverage-clover <file>: Save the code coverage report in Clover XML format to a specified file.
• --coverage-cobertura <file>: Save the code coverage report in Cobertura XML format to a specified file.
• --coverage-crap4j <file>: Save the code coverage report in Crap4J XML format to a specified file.
• --coverage-html <dir>: Save the code coverage report in HTML format to a specified directory.
• --coverage-php <file>: Serialize the code coverage data and save it to a specified file.
• --coverage-text=<file>: Save the code coverage report in text format to a specified file. (Default: php://stdout)
• --coverage-xml <dir>: Save the code coverage report in XML format to a specified directory.

In this chapter, we've discussed test coverage and how it helps you determine the percentage of your application that is actually tested. In the following chapter, we will dive into Pest's Type Coverage Plugin: Type Coverage