aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/dev/Unit-tests.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md/dev/Unit-tests.md')
-rw-r--r--doc/md/dev/Unit-tests.md138
1 files changed, 138 insertions, 0 deletions
diff --git a/doc/md/dev/Unit-tests.md b/doc/md/dev/Unit-tests.md
new file mode 100644
index 00000000..25af82d7
--- /dev/null
+++ b/doc/md/dev/Unit-tests.md
@@ -0,0 +1,138 @@
1# Unit tests
2
3Shaarli 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
7You 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:
37sudo aptitude install php5-xdebug
38
39# for ArchLinux:
40pacman -S xdebug
41
42# then add the following line to /etc/php/php.ini
43zend_extension=xdebug.so
44```
45
46## Run unit tests
47
48Ensure tests pass successuflly:
49
50```bash
51make test
52# ...
53# OK (36 tests, 65 assertions)
54```
55
56In case of failure the test suite will point you to actual errors and output a summary:
57
58```bash
59make test
60# ...
61# FAILURES!
62# Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
63```
64
65By 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
75If 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
84Add 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 */
91class BookmarkImportTest extends PHPUnit_Framework_TestCase
92{
93 [...]
94}
95```
96
97To 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
104Unit tests can be run inside [Docker](../Docker.md) containers.
105
106Test 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
113Each 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
120Build a test image:
121
122```bash
123# build the Debian 9 Docker image
124cd /path/to/shaarli/tests/docker/debian9
125docker build -t shaarli-test:debian9 .
126```
127
128Run unit tests in a container:
129
130```bash
131cd /path/to/shaarli
132# install/update 3rd-party test dependencies
133composer install --prefer-dist
134# run tests using the freshly built image
135docker run -v $PWD:/shaarli shaarli-test:debian9 docker_test
136# run the full test campaign
137docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests
138```