]>
Commit | Line | Data |
---|---|---|
91a21c27 | 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 | # 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: | |
37 | sudo aptitude install php5-xdebug | |
38 | ||
39 | # for ArchLinux: | |
40 | pacman -S xdebug | |
41 | ||
42 | # then add the following line to /etc/php/php.ini | |
43 | zend_extension=xdebug.so | |
44 | ``` | |
45 | ||
46 | ## Run unit tests | |
47 | ||
48 | Ensure tests pass successuflly: | |
49 | ||
50 | ```bash | |
51 | make test | |
52 | # ... | |
53 | # OK (36 tests, 65 assertions) | |
54 | ``` | |
55 | ||
56 | In case of failure the test suite will point you to actual errors and output a summary: | |
57 | ||
58 | ```bash | |
59 | make test | |
60 | # ... | |
61 | # FAILURES! | |
62 | # Tests: 36, Assertions: 63, Errors: 1, Failures: 2. | |
63 | ``` | |
64 | ||
65 | By 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 | ||
75 | If 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 | ||
84 | Add 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 | */ | |
91 | class BookmarkImportTest extends PHPUnit_Framework_TestCase | |
92 | { | |
93 | [...] | |
94 | } | |
95 | ``` | |
96 | ||
97 | To 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 | ||
104 | Unit tests can be run inside [Docker](../Docker.md) containers. | |
105 | ||
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: | |
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 | ||
113 | Each 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 | ||
120 | Build a test image: | |
121 | ||
122 | ```bash | |
123 | # build the Debian 9 Docker image | |
124 | cd /path/to/shaarli/tests/docker/debian9 | |
125 | docker build -t shaarli-test:debian9 . | |
126 | ``` | |
127 | ||
128 | Run unit tests in a container: | |
129 | ||
130 | ```bash | |
131 | cd /path/to/shaarli | |
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 | |
138 | ``` |