[Summary view] [Print] [Text view]

   1  @title Writing Unit Tests
   2  @group developer
   3  
   4  Simple guide to libphutil, Arcanist and Phabricator unit tests.
   5  
   6  = Overview =
   7  
   8  libphutil, Arcanist and Phabricator provide and use a simple unit test
   9  framework. This document is aimed at project contributors and describes how to
  10  use it to add and run tests in these projects or other libphutil libraries.
  11  
  12  In the general case, you can integrate ##arc## with a custom unit test engine
  13  (like PHPUnit or any other unit testing library) to run tests in other projects.
  14  See @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
  15  for information on customizing engines.
  16  
  17  = Adding Tests =
  18  
  19  To add new tests to a libphutil, Arcanist or Phabricator module:
  20  
  21    - Create a ##__tests__/## directory in the module if it doesn't exist yet.
  22    - Add classes to the ##__tests__/## directory which extend from
  23      @{class:PhabricatorTestCase} (in Phabricator) or
  24      @{class@arcanist:ArcanistPhutilTestCase} (elsewhere).
  25    - Run ##arc liberate## on the library root so your classes are loadable.
  26  
  27  = Running Tests =
  28  
  29  Once you've added test classes, you can run them with:
  30  
  31    - ##arc unit path/to/module/##, to explicitly run module tests.
  32    - ##arc unit##, to run tests for all modules affected by changes in the
  33      working copy.
  34    - ##arc diff## will also run ##arc unit## for you.
  35  
  36  = Example Test Case =
  37  
  38  Here's a simple example test:
  39  
  40    lang=php
  41    class PhabricatorTrivialTestCase extends PhabricatorTestCase {
  42  
  43      private $two;
  44  
  45      public function willRunOneTest($test_name) {
  46        // You can execute setup steps which will run before each test in this
  47        // method.
  48        $this->two = 2;
  49      }
  50  
  51      public function testAllIsRightWithTheWorld() {
  52        $this->assertEqual(4, $this->two + $this->two, '2 + 2 = 4');
  53      }
  54  
  55    }
  56  
  57  You can see this class at @{class:PhabricatorTrivialTestCase} and run it with:
  58  
  59    phabricator/ $ arc unit src/infrastructure/testing/testcase/
  60     PASS   <1ms*  testAllIsRightWithTheWorld
  61  
  62  For more information on writing tests, see
  63  @{class@arcanist:ArcanistPhutilTestCase} and @{class:PhabricatorTestCase}.
  64  
  65  = Database Isolation =
  66  
  67  By default, Phabricator isolates unit tests from the database. It makes a crude
  68  effort to simulate some side effects (principally, ID assignment on insert), but
  69  any queries which read data will fail to select any rows and throw an exception
  70  about isolation. In general, isolation is good, but this can make certain types
  71  of tests difficult to write. When you encounter issues, you can deal with them
  72  in a number of ways. From best to worst:
  73  
  74    - Encounter no issues; your tests are fast and isolated.
  75    - Add more simulated side effects if you encounter minor issues and simulation
  76      is reasonable.
  77    - Build a real database simulation layer (fairly complex).
  78    - Disable isolation for a single test by using
  79      ##LiskDAO::endIsolateAllLiskEffectsToCurrentProcess();## before your test
  80      and ##LiskDAO::beginIsolateAllLiskEffectsToCurrentProcess();## after your
  81      test. This will disable isolation for one test. NOT RECOMMENDED.
  82    - Disable isolation for your entire test case by overriding
  83      ##getPhabricatorTestCaseConfiguration()## and providing
  84      ##self::PHABRICATOR_TESTCONFIG_ISOLATE_LISK => false## in the configuration
  85      dictionary you return. This will disable isolation entirely. STRONGLY NOT
  86      RECOMMENDED.