[Summary view] [Print] [Text view]

   1  @title Arcanist User Guide: Code Coverage
   2  @group userguide
   3  
   4  Explains code coverage features in Arcanist and Phabricator.
   5  
   6  This is a configuration guide that helps you set up advanced features. If you're
   7  just getting started, you don't need to look at this yet. Instead, start with
   8  the @{article:Arcanist User Guide}.
   9  
  10  Before you can configure coverage features, you must set up unit test
  11  integration. For instructions, see @{article:Arcanist User Guide: Configuring
  12  a New Project} and @{article:Arcanist User Guide: Customizing
  13  Lint, Unit Tests and Workflows}.
  14  
  15  = Using Coverage Features =
  16  
  17  If your project has unit tests with coverage integration (see below for
  18  instructions on setting it up), you can use "arc" to show coverage reports.
  19  
  20  For example:
  21  
  22    arc unit --detailed-coverage src/some/file.php
  23  
  24  Depending on how your test engine is configured, this will run tests relevant
  25  to ##src/some/file.php## and give you a detailed coverage report.
  26  
  27  If the test engine enables coverage by default, it will be uploaded to
  28  Differential and displayed in the right gutter when viewing diffs.
  29  
  30  = Enabling Coverage for libphutil, Arcanist and Phabricator =
  31  
  32  If you're contributing, libphutil, Arcanist and Phabricator support coverage if
  33  you install Xdebug:
  34  
  35  http://xdebug.org/
  36  
  37  It should be sufficient to correctly install Xdebug; coverage information will
  38  be automatically enabled.
  39  
  40  = Building Coverage Support =
  41  
  42  To add coverage support to a unit test engine, just call ##setCoverage()## when
  43  building @{class@arcanist:ArcanistUnitTestResult} objects. Provide a map of
  44  file names (relative to the working copy root) to coverage report strings.
  45  Coverage report strings look like this:
  46  
  47    NNNNNCCCNNNNNNNNCCCCCCNNNUUUNNNNN
  48  
  49  Each line in the file is represented by a character. Valid characters are:
  50  
  51    - **N** Not executable. This is a comment or whitespace which should be
  52      ignored when computing test coverage.
  53    - **C** Covered. This line has test coverage.
  54    - **U** Uncovered. This line is executable but has no test coverage.
  55    - **X** Unreachable. If your coverage analysis can detect unreachable code,
  56      you can report it here.
  57  
  58  This format is intended to be as simple as possible. A valid coverage result
  59  might look like this:
  60  
  61    array(
  62      'src/example.php' => 'NNCNNNCNUNNNUNUNUNUNUNC',
  63      'src/other.php'   => 'NNUNNNUNCNNNUNUNCNCNCNU',
  64    );
  65  
  66  You may also want to filter coverage information to the paths passed to the
  67  unit test engine. See @{class@arcanist:ArcanistPhutilTestCase} and
  68  @{class@arcanist:PhutilUnitTestEngine} for an example of coverage integration
  69  in PHP using Xdebug.