@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Arcanist User Guide: Code Coverage
2@group userguide
3
4Explains code coverage features in Arcanist and Phorge.
5
6This is a configuration guide that helps you set up advanced features. If you're
7just getting started, you don't need to look at this yet. Instead, start with
8the @{article:Arcanist User Guide}.
9
10Before you can configure coverage features, you must set up unit test
11integration. For instructions, see @{article:Arcanist User Guide: Configuring
12a New Project} and @{article:Arcanist User Guide: Customizing
13Lint, Unit Tests and Workflows}.
14
15= Using Coverage Features =
16
17If your project has unit tests with coverage integration (see below for
18instructions on setting it up), you can use "arc" to show coverage reports.
19
20For example:
21
22 arc unit --detailed-coverage src/some/file.php
23
24Depending on how your test engine is configured, this will run tests relevant
25to `src/some/file.php` and give you a detailed coverage report.
26
27If the test engine enables coverage by default, it will be uploaded to
28Differential and displayed in the right gutter when viewing diffs.
29
30= Enabling Coverage for Arcanist and Phorge =
31
32If you're contributing, Arcanist and Phorge support coverage if
33you install Xdebug:
34
35http://xdebug.org/
36
37It should be sufficient to correctly install Xdebug; coverage information will
38be automatically enabled.
39
40= Building Coverage Support =
41
42To add coverage support to a unit test engine, just call `setCoverage()` when
43building @{class@arcanist:ArcanistUnitTestResult} objects. Provide a map of
44file names (relative to the working copy root) to coverage report strings.
45Coverage report strings look like this:
46
47 NNNNNCCCNNNNNNNNCCCCCCNNNUUUNNNNN
48
49Each 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
58This format is intended to be as simple as possible. A valid coverage result
59might look like this:
60
61 array(
62 'src/example.php' => 'NNCNNNCNUNNNUNUNUNUNUNC',
63 'src/other.php' => 'NNUNNNUNCNNNUNUNCNCNCNU',
64 );
65
66You may also want to filter coverage information to the paths passed to the
67unit test engine. See @{class@arcanist:PhutilTestCase} and
68@{class@arcanist:PhutilUnitTestEngine} for an example of coverage integration
69in PHP using Xdebug.