[Summary view] [Print] [Text view]

   1  # Unit Tests for [YOURLS](https://github.com/YOURLS/YOURLS/)
   2  
   3  ## About
   4  
   5  This is the unit test suite for YOURLS: a collection of hundreds of tests to make sure that whenever something in YOURLS is added, changed or removed, everything still works under all the supported PHP versions.
   6  
   7  ## Getting Started
   8  
   9  If you want to run tests locally:
  10  
  11  0. Install PHPUnit.
  12     ```bash
  13     composer -d tests/ install
  14     ```
  15  1. Create an empty MySQL database and user. **Do not use an exisiting database** or you will lose data, guaranteed.
  16  3. Copy `<YOURLS_ROOT>tests/data/config/yourls-tests-config-sample.php` to `<YOURLS_ROOT>/tests/yourls-tests-config.php` and edit it to match your setup.
  17     ```bash
  18     cp tests/data/config/yourls-tests-config-sample.php tests/yourls-tests-config.php
  19     ```
  20  4. In YOURLS root directory, you can now run the shell command:
  21     ```bash
  22     composer -d tests/ run test -- --configuration=../phpunit.xml.dist ..
  23     ```
  24  
  25  Hopefully you should see something like the following appear:
  26  
  27  ```
  28  YOURLS installed, starting PHPUnit
  29  
  30  PHPUnit by Sebastian Bergmann and contributors.
  31  
  32  Configuration: ...\phpunit.xml.dist
  33  
  34  ...............................................................  63 / 519 ( 12%)
  35  ............................................................... 126 / 519 ( 24%)
  36  ............................................................... 189 / 519 ( 36%)
  37  ............................................................... 252 / 519 ( 48%)
  38  ............................................................... 315 / 519 ( 60%)
  39  ............................................................... 378 / 519 ( 72%)
  40  ............................................................... 441 / 519 ( 84%)
  41  ............................................................... 504 / 519 ( 97%)
  42  ...............                                                 519 / 519 (100%)
  43  
  44  Time: 6.06 seconds, Memory: 24.25Mb
  45  
  46  OK (519 tests, 1123 assertions)
  47  ```
  48  
  49  You can elect to run only selected groups of tests, eg:
  50  
  51  ```bash
  52  $ phpunit --group formatting
  53  ```
  54  
  55  PHPUnit supports both `phpunit.xml` and `phpunit.xml.dist`, where `phpunit.xml` has higher priority:
  56  if you want to specify your own settings, copy `phpunit.xml.dist` to `phpunit.xml` and edit that file.
  57  
  58  ## Testing in a new process
  59  
  60  Some things can only happen once per PHP process: a constant being defined, a file
  61  being loaded with `require_once`. Asserting on them from within the test suite only
  62  tells you what an earlier test happened to trigger first. For those, run a *scenario*
  63  in a fresh process:
  64  
  65  ```php
  66  class SomeTest extends PHPUnit\Framework\TestCase {
  67      use NewProcessTrait;
  68  
  69      public function test_something() {
  70          $report = $this->run_in_new_process( 'some-scenario', array( 'YOURLS_SOMETHING' => false ) );
  71  
  72          $this->assertArrayNotHasKey( 'YOURLS_USER', $report['constants'] );
  73          $this->assertNotContains( 'includes/auth.php', $report['included'] );
  74      }
  75  }
  76  
  77  The trait (tests/includes/new-process.php) runs tests/data/scripts/run-scenario.php
  78  in a new process, which:
  79  
  80  1. defines the constants asked for, before anything else, so config and core see them
  81  2. boots the same YOURLS as the test suite, via yut_boot_yourls() (tests/includes/boot.php)
  82  3. runs tests/data/scripts/scenarios/some-scenario.php
  83  4. reports back, as JSON, every defined YOURLS_* constant and every file loaded below
  84  YOURLS_ABSPATH
  85  
  86  Testing something else is a matter of dropping a new file in scenarios/: plain PHP,
  87  run once YOURLS is booted, no assertions in it -- it only acts, the test asserts on the
  88  report. Note that the database is expected to be already installed by the test suite.