doc/md/dev/Unit-tests.md

   1 # Unit tests
   2
   3 Shaarli uses the [PHPUnit](https://phpunit.de/) test framework; it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
   4
   5 ## Install composer
   6
   7 You can either use:
   8
   9 - a system-wide version, e.g. installed through your distro's package manager
  10 - a local version, downloadable [here](https://getcomposer.org/download/).
  11
  12 ```bash
  13 # system-wide version
  14 $ composer install
  15 $ composer update
  16
  17 # local version
  18 $ php composer.phar self-update
  19 $ php composer.phar install
  20 $ php composer.phar update
  21 ```
  22
  23 ## Install Shaarli dev dependencies
  24
  25 ```bash
  26 $ cd /path/to/shaarli
  27 $ composer update
  28 ```
  29
  30 ## Install and enable Xdebug to generate PHPUnit coverage reports
  31
  32
  33 [Xdebug](http://xdebug.org/docs/install) is a PHP extension which provides debugging and profiling capabilities. Install Xdebug:
  34
  35 ```bash
  36 # for Debian-based distros:
  37 sudo aptitude install php5-xdebug
  38
  39 # for ArchLinux:
  40 pacman -S xdebug
  41
  42 # then add the following line to /etc/php/php.ini
  43 zend_extension=xdebug.so
  44 ```
  45
  46 ## Run unit tests
  47
  48 Ensure tests pass successuflly:
  49
  50 ```bash
  51 make test
  52 # ...
  53 # OK (36 tests, 65 assertions)
  54 ```
  55
  56 In case of failure the test suite will point you to actual errors and output a summary:
  57
  58 ```bash
  59 make test
  60 # ...
  61 # FAILURES!
  62 # Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
  63 ```
  64
  65 By default, PHPUnit will run all suitable tests found under the `tests` directory. Each test has 3 possible outcomes:
  66
  67 - `.` - success
  68 - `F` - failure: the test was run but its results are invalid
  69     - the code does not behave as expected
  70     - dependencies to external elements: globals, session, cache...
  71 - `E` - error: something went wrong and the tested code has crashed
  72     - typos in the code, or in the test code
  73     - dependencies to missing external elements
  74
  75 If Xdebug has been installed and activated, two coverage reports will be generated:
  76
  77 - a summary in the console
  78 - a detailed HTML report with metrics for tested code
  79     - to open it in a web browser: `firefox coverage/index.html &`
  80
  81
  82 ### Executing specific tests
  83
  84 Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:
  85
  86 ```php
  87 /**
  88  * Netscape bookmark import
  89  * @group WIP
  90  */
  91 class BookmarkImportTest extends PHPUnit_Framework_TestCase
  92 {
  93    [...]
  94 }
  95 ```
  96
  97 To run all tests annotated with `@group WIP`:
  98 ```bash
  99 $ vendor/bin/phpunit --group WIP tests/
 100 ```
 101
 102 ## Running tests inside Docker containers
 103
 104 Unit tests can be run inside [Docker](../Docker.md) containers.
 105
 106 Test Dockerfiles are located under `tests/docker/<distribution>/Dockerfile`, and can be used to build Docker images to run Shaarli test suites under commonLinux environments. Dockerfiles are provided for the following environments:
 107
 108 - [`alpine36`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/alpine36/Dockerfile) - [Alpine Linux 3.6](https://www.alpinelinux.org/downloads/)
 109 - [`debian8`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian8/Dockerfile) - [Debian 8 Jessie](https://www.debian.org/DebianJessie) (oldoldstable)
 110 - [`debian9`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian9/Dockerfile) - [Debian 9 Stretch](https://wiki.debian.org/DebianStretch) (oldstable)
 111 - [`ubuntu16`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/ubuntu16/Dockerfile) - [Ubuntu 16.04 Xenial Xerus](http://releases.ubuntu.com/16.04/) (old LTS)
 112
 113 Each image provides:
 114 - a base Linux OS
 115 - Shaarli PHP dependencies (OS packages)
 116 - test PHP dependencies (OS packages)
 117 - Composer
 118 - Tests that run inside the conatiner using a standard Linux user account (running tests as `root` would bypass permission checks and may hide issues)
 119
 120 Build a test image:
 121
 122 ```bash
 123 # build the Debian 9 Docker image
 124 cd /path/to/shaarli/tests/docker/debian9
 125 docker build -t shaarli-test:debian9 .
 126 ```
 127
 128 Run unit tests in a container:
 129
 130 ```bash
 131 cd /path/to/shaarli
 132 # install/update 3rd-party test dependencies
 133 composer install --prefer-dist
 134 # run tests using the freshly built image
 135 docker run -v $PWD:/shaarli shaarli-test:debian9 docker_test
 136 # run the full test campaign
 137 docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests
 138 ```