aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Unit-tests.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md/Unit-tests.md')
-rw-r--r--doc/md/Unit-tests.md152
1 files changed, 152 insertions, 0 deletions
diff --git a/doc/md/Unit-tests.md b/doc/md/Unit-tests.md
new file mode 100644
index 00000000..19838721
--- /dev/null
+++ b/doc/md/Unit-tests.md
@@ -0,0 +1,152 @@
1### Setup your environment for tests
2
3The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
4
5Regarding Composer, you can either use:
6* a system-wide version, e.g. installed through your distro's package manager
7* a local version, downloadable [here](https://getcomposer.org/download/)
8
9#### Sample usage
10
11```bash
12# system-wide version
13$ composer install
14$ composer update
15
16# local version
17$ php composer.phar self-update
18$ php composer.phar install
19$ php composer.phar update
20```
21
22#### Install Shaarli dev dependencies
23
24```bash
25$ cd /path/to/shaarli
26$ composer update
27```
28
29#### Install and enable Xdebug to generate PHPUnit coverage reports
30
31For Debian-based distros:
32```bash
33$ aptitude install php5-xdebug
34```
35For ArchLinux:
36```bash
37$ pacman -S xdebug
38```
39
40Then add the following line to `/etc/php/php.ini`:
41```ini
42zend_extension=xdebug.so
43```
44
45#### Run unit tests
46
47Successful test suite:
48```bash
49$ make test
50
51-------
52PHPUNIT
53-------
54PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
55
56Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
57
58....................................
59
60Time: 759 ms, Memory: 8.25Mb
61
62OK (36 tests, 65 assertions)
63```
64
65Test suite with failures and errors:
66```bash
67$ make test
68-------
69PHPUNIT
70-------
71PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
72
73Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
74
75E..FF...............................
76
77Time: 802 ms, Memory: 8.25Mb
78
79There was 1 error:
80
811) LinkDBTest::testConstructLoggedIn
82Missing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\
83DBTest.php on line 79 and defined
84
85/home/virtualtam/public_html/shaarli/application/LinkDB.php:58
86/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79
87
88--
89
90There were 2 failures:
91
921) LinkDBTest::testCheckDBNew
93Failed asserting that two strings are equal.
94--- Expected
95+++ Actual
96@@ @@
97-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
98+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
99
100/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121
101
1022) LinkDBTest::testCheckDBLoad
103Failed asserting that two strings are equal.
104--- Expected
105+++ Actual
106@@ @@
107-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
108+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
109
110/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
111
112FAILURES!
113Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
114```
115
116#### Test results and coverage
117
118By default, PHPUnit will run all suitable tests found under the `tests` directory.
119
120Each test has 3 possible outcomes:
121* `.` - success
122* `F` - failure: the test was run but its results are invalid
123 * the code does not behave as expected
124 * dependencies to external elements: globals, session, cache...
125* `E` - error: something went wrong and the tested code has crashed
126 * typos in the code, or in the test code
127 * dependencies to missing external elements
128
129If Xdebug has been installed and activated, two coverage reports will be generated:
130* a summary in the console
131* a detailed HTML report with metrics for tested code
132 * to open it in a web browser: `firefox coverage/index.html &`
133
134### Executing specific tests
135
136Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:
137
138```php
139/**
140 * Netscape bookmark import
141 * @group WIP
142 */
143class BookmarkImportTest extends PHPUnit_Framework_TestCase
144{
145 [...]
146}
147```
148
149To run all tests annotated with `@group WIP`:
150```bash
151$ vendor/bin/phpunit --group WIP tests/
152```