phorge-phorge/src/docs/user/userguide/arcanist_coverage.diviner

@title Arcanist User Guide: Code Coverage
@group userguide

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 @{article:Arcanist User Guide}.

Before you can configure coverage features, you must set up unit test
integration. For instructions, see @{article:Arcanist User Guide: Configuring
a New Project} and @{article: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 @{class@arcanist: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 @{class@arcanist:PhutilTestCase} and
@{class@arcanist:PhutilUnitTestEngine} for an example of coverage integration
in PHP using Xdebug.