...

Code coverage is a valuable tool to identify gaps in your test suite and ensure that your code is adequately covered by tests. However, high code coverage alone does not guarantee high-quality tests. It is critical to focus on writing well-constructed tests, as this will have a greater impact than striving to cover every line of code.

PHPUnit and

...

code coverage

PHPUnit provides built-in support for generating code coverage reports in various formats. To generate code coverage, PHPUnit relies on either XDebug or pcov. While pcov is more performant than XDebug, this guide demonstrates how to use both.

Configuring and

...

generating code coverage reports (latest version)

...

Step 1: Initialise PHPUnit

php test/phpunit/phpunit.php init

Step 2: Configure

...

whitelists

To generate code coverage, you need to define a whitelist in your phpunit.xml file. Without this, you will encounter the following error:

...

File: test/phpunit/phpunit.xml

<source>
    <include>
        <directory suffix=".php">/var/www/totara/src/SITENAME/server/totara/core/classes/local</directory>
        <directory suffix=".php">/var/www/totara/src/SITENAME/server/totara/core/classes/task</directory>
        <file>/var/www/totara/src/SITENAME/server/totara/core/classes/visibility_adviser.php</file>
    </include>
</source>

Important

...

notes

• Use full paths to avoid incorrect whitelist configuration errors.

• You can also use <exclude> tags. Please refer to the PHPUnit documentation for the full configuration details.

• Limit the whitelist to relevant files and directories to reduce the report generation time.

• If <source> does not work, replace it with <coverage>.

Step 3: Generate

...

coverage reports

Using XDebug

Ensure XDebug is installed. Use the following commands to generate an HTML-formatted coverage report:

...

1. Install pcov:

   Code Block
   pecl install pcov

   Note the generated path to pcov.so, e.g. , /usr/local/lib/php/extensions/no-debug-non-zts-20230831/pcov.so.

2. Update php.ini. Note here also that we update the memory_limit to 8G:

   Code Block
   language ini
   memory_limit=8G [pcov] extension="path/to/pcov.so" pcov.enabled=1 pcov.exclude='~(vendor|tests|node_modules|.git|client|.scannerwork)~' pcov.initial.memory=1073741824 pcov.initial.files=30000

3. Generate the report:

   Code Block
   phpunit --coverage-html /var/www/html/coverage_report /path/to/plugin/to/test

Viewing the reportusing Totara docker developer environment

...

3. Now you should be able to access your coverage report via the web browser by navigating to http://coverage_report.totaraXX, where XX is the PHP version you used in step 2.

Configurations for

...

older versions

Totara 13

Initialisation:

php test/phpunit/phpunit.php init

Whitelist Configurationconfiguration:

<filter>
    <whitelist>
        <directory suffix=".php">/var/www/totara/src/SITENAME/server/totara/core/classes/local</directory>
        <directory suffix=".php">/var/www/totara/src/SITENAME/server/totara/core/classes/task</directory>
        <file>/var/www/totara/src/SITENAME/server/totara/core/classes/visibility_adviser.php</file>
    </whitelist>
</filter>

Generating Coverage Reportscoverage reports:

XDEBUG_MODE=coverage php test/phpunit/phpunit.php run --filter=totara_core --coverage-html /var/www/totara/src/dev/coverage

...

php admin/tool/phpunit/cli/init.php

Whitelist Configurationconfiguration:

<filter>
    <whitelist processUncoveredFilesFromWhitelist="false" addUncoveredFilesFromWhitelist="false">
        <directory suffix=".php">/var/www/totara/src/SITENAME/totara/core/classes/local</directory>
        <directory suffix=".php">/var/www/totara/src/SITENAME/totara/core/classes/task</directory>
        <file>/var/www/totara/src/SITENAME/totara/core/classes/visibility_adviser.php</file>
    </whitelist>
</filter>

Generating Coverage Reportscoverage reports:

XDEBUG_MODE=coverage vendor/bin/phpunit --filter=totara_core --coverage-html /var/www/html/coverage_report

...

Install pcov/clobber which adds pcov support to PHPUnit 7:

composer require pcov/clobber
vendor/bin/pcov clobber

...

PHPStorm has the ability to run code coverage anaylsis analysis in product using XDebug or pcov. The analysis is automatically loaded into the platform and displayed both in the Coverage coverage tool, and in-editor when looking at files. Their documentation on code coverage explains how to set it up.

A Here are a few pointers and tips to help however:

• You still need to define a whitelist

• As a product we support several different versions of PHP - if you're using php-fpm and have them installed you can configure PHPStorm so that you can choose which version you run tests and coverage on

• When looking at a testcase file you can click on the little arrows next to test case classes and test case methods and choose to run specific tests

Common

...

pitfalls

1. Incorrect phpunit.xml Paths paths: Ensure paths point to the correct Totara installation.

2. Whitelist Misconfigurationmisconfiguration: Use pwd to verify paths and ensure full paths in your configuration.

...