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.
9 - a system-wide version, e.g. installed through your distro's package manager
10 - a local version, downloadable [here](https://getcomposer.org/download/).
13 # for Debian-based distros
14 sudo apt install composer
18 ## Install Shaarli dev dependencies
22 $ make composer_dependencies_dev
25 ## Install and enable Xdebug to generate PHPUnit coverage reports
28 [Xdebug](http://xdebug.org/docs/install) is a PHP extension which provides debugging and profiling capabilities. Install Xdebug:
31 # for Debian-based distros:
32 sudo apt install php-xdebug
37 # then add the following line to /etc/php/php.ini
38 zend_extension=xdebug.so
43 Ensure tests pass successuflly:
48 # OK (36 tests, 65 assertions)
51 In case of failure the test suite will point you to actual errors and output a summary:
57 # Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
60 By default, PHPUnit will run all suitable tests found under the `tests` directory. Each test has 3 possible outcomes:
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
70 If Xdebug has been installed and activated, two coverage reports will be generated:
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 &`
77 ### Executing specific tests
79 Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:
83 * Netscape bookmark import
86 class BookmarkImportTest extends PHPUnit_Framework_TestCase
92 To run all tests annotated with `@group WIP`:
94 $ vendor/bin/phpunit --group WIP tests/
97 ## Running tests inside Docker containers
99 Unit tests can be run inside [Docker](../Docker.md) containers.
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:
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)
110 - Shaarli PHP dependencies (OS packages)
111 - test PHP dependencies (OS packages)
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)
118 # build the Debian 9 Docker image
119 cd /path/to/shaarli/tests/docker/debian9
120 docker build -t shaarli-test:debian9 .
123 Run unit tests in a container:
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