]>
Commit | Line | Data |
---|---|---|
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 | ``` |