@title Writing Unit Tests
@group developer

Simple guide to libphutil, Arcanist and Phabricator unit tests.

= Overview =

libphutil, Arcanist and Phabricator provide and use a simple unit test
framework. This document is aimed at project contributors and describes how to
use it to add and run tests in these projects or other libphutil libraries.

In the general case, you can integrate ##arc## with a custom unit test engine
(like PHPUnit or any other unit testing library) to run tests in other projects.
See @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
for information on customizing engines.

= Adding Tests =

To add new tests to a libphutil, Arcanist or Phabricator module:

  - Create a ##__tests__/## directory in the module if it doesn't exist yet.
  - Add classes to the ##__tests__/## directory which extend from
    @{class:PhabricatorTestCase} (in Phabricator) or
    @{class@arcanist:ArcanistPhutilTestCase} (elsewhere).
  - Run ##arc liberate## on the library root so your classes are loadable.

= Running Tests =

Once you've added test classes, you can run them with:

  - ##arc unit path/to/module/##, to explicitly run module tests.
  - ##arc unit##, to run tests for all modules affected by changes in the
    working copy.
  - ##arc diff## will also run ##arc unit## for you.