055e8f07ab
Summary: There's some good feedback from Wikimedia here: http://lists.wikimedia.org/pipermail/wikitech-l/2012-August/062252.html Try to improve on some of it. In particular: - Make it clear that /arcanist/ is not where you should be (D3235). - Provide better connections from "Arcanist User Guide" to other documents. - Provide a "Quick Start" guide with a simpler set of instructions that links to richer documentation. - Reorganize the project setup guide to put more important things earlier on. - Make it clear that you should commit `.arcconfig`. - Provide more hints for initial setup. - Describe and organize advanced configuration/extension documentation as more clearly separate from basic setup/install documentation. Test Plan: Generated, read docs. Reviewers: vrana, btrahan Reviewed By: vrana CC: aran Differential Revision: https://secure.phabricator.com/D3236
69 lines
2.5 KiB
Plaintext
69 lines
2.5 KiB
Plaintext
@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:ArcanistPhutilTestCase} and
|
|
@{class@arcanist:PhutilUnitTestEngine} for an example of coverage integration
|
|
in PHP using Xdebug. |