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/).
18 $ php composer.phar self-update
19 $ php composer.phar install
20 $ php composer.phar update
23 ## Install Shaarli dev dependencies
30 ## Install and enable Xdebug to generate PHPUnit coverage reports
33 [Xdebug](http://xdebug.org/docs/install) is a PHP extension which provides debugging and profiling capabilities. Install Xdebug:
36 # for Debian-based distros:
37 sudo aptitude install php5-xdebug
42 # then add the following line to /etc/php/php.ini
43 zend_extension=xdebug.so
48 Ensure tests pass successuflly:
53 # OK (36 tests, 65 assertions)
56 In case of failure the test suite will point you to actual errors and output a summary:
62 # Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
65 By default, PHPUnit will run all suitable tests found under the `tests` directory. Each test has 3 possible outcomes:
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
75 If Xdebug has been installed and activated, two coverage reports will be generated:
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 &`
82 ### Executing specific tests
84 Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:
88 * Netscape bookmark import
91 class BookmarkImportTest extends PHPUnit_Framework_TestCase
97 To run all tests annotated with `@group WIP`:
99 $ vendor/bin/phpunit --group WIP tests/
102 ## Running tests inside Docker containers
104 Unit tests can be run inside [Docker](../Docker.md) containers.
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:
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)
115 - Shaarli PHP dependencies (OS packages)
116 - test PHP dependencies (OS packages)
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)
123 # build the Debian 9 Docker image
124 cd /path/to/shaarli/tests/docker/debian9
125 docker build -t shaarli-test:debian9 .
128 Run unit tests in a container:
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