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