Article Arcanist User Guide: Code Coverage

Explains code coverage features in Arcanist and Phabricator.

This is a configuration guide that helps you set up advanced features. If you're just getting started, you don't need to look at this yet. Instead, start with the Arcanist User Guide.

Before you can configure coverage features, you must set up unit test integration. For instructions, see Arcanist User Guide: Configuring a New Project and Arcanist User Guide: Customizing Lint, Unit Tests and Workflows.

Using Coverage Features

If your project has unit tests with coverage integration (see below for instructions on setting it up), you can use "arc" to show coverage reports.

For example:

arc unit --detailed-coverage src/some/file.php

Depending on how your test engine is configured, this will run tests relevant to src/some/file.php and give you a detailed coverage report.

If the test engine enables coverage by default, it will be uploaded to Differential and displayed in the right gutter when viewing diffs.

Enabling Coverage for libphutil, Arcanist and Phabricator

If you're contributing, libphutil, Arcanist and Phabricator support coverage if you install Xdebug:

http://xdebug.org/

It should be sufficient to correctly install Xdebug; coverage information will be automatically enabled.

Building Coverage Support

To add coverage support to a unit test engine, just call setCoverage() when building ArcanistUnitTestResult objects. Provide a map of file names (relative to the working copy root) to coverage report strings. Coverage report strings look like this:

NNNNNCCCNNNNNNNNCCCCCCNNNUUUNNNNN

Each line in the file is represented by a character. Valid characters are:

• N Not executable. This is a comment or whitespace which should be ignored when computing test coverage.
• C Covered. This line has test coverage.
• U Uncovered. This line is executable but has no test coverage.
• X Unreachable. If your coverage analysis can detect unreachable code, you can report it here.

This format is intended to be as simple as possible. A valid coverage result might look like this:

array(
  'src/example.php' => 'NNCNNNCNUNNNUNUNUNUNUNC',
  'src/other.php'   => 'NNUNNNUNCNNNUNUNCNCNCNU',
);

You may also want to filter coverage information to the paths passed to the unit test engine. See ArcanistPhutilTestCase and PhutilUnitTestEngine for an example of coverage integration in PHP using Xdebug.