Unit tests#
Shaarli uses the PHPUnit test framework; it can be installed with Composer, which is a dependency management tool.
Install composer#
You can either use:
- a system-wide version, e.g. installed through your distro's package manager
- a local version, downloadable here.
# for Debian-based distros
sudo apt install composer
Install Shaarli dev dependencies#
After installing required PHP extensions, install development dependencies:
$ cd /path/to/shaarli
$ make composer_dependencies_dev
Install and enable Xdebug to generate PHPUnit coverage reports#
Xdebug is a PHP extension which provides debugging and profiling capabilities. Install Xdebug:
# for Debian-based distros:
sudo apt install php-xdebug
# for ArchLinux:
pacman -S xdebug
# then add the following line to /etc/php/php.ini
zend_extension=xdebug.so
Run unit tests#
Ensure tests pass successfully:
make test
# ...
# OK (36 tests, 65 assertions)
In case of failure the test suite will point you to actual errors and output a summary:
make test
# ...
# FAILURES!
# Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
By default, PHPUnit will run all suitable tests found under the tests
directory. Each test has 3 possible outcomes:
.
- successF
- failure: the test was run but its results are invalid- the code does not behave as expected
- dependencies to external elements: globals, session, cache...
E
- error: something went wrong and the tested code has crashed- typos in the code, or in the test code
- dependencies to missing external elements
If Xdebug has been installed and activated, two coverage reports will be generated:
- a summary in the console
- a detailed HTML report with metrics for tested code
- to open it in a web browser:
firefox coverage/index.html &
- to open it in a web browser:
Executing specific tests#
Add a @group
annotation in a test class or method comment:
/**
* Netscape bookmark import
* @group WIP
*/
class BookmarkImportTest extends PHPUnit_Framework_TestCase
{
[...]
}
To run all tests annotated with @group WIP
:
$ vendor/bin/phpunit --group WIP tests/
Running tests inside Docker containers#
Unit tests can be run inside Docker containers.
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:
alpine316
- Alpine Linux 3.16debian8
- Debian 8 Jessie (oldoldstable)debian9
- Debian 9 Stretch (oldstable)ubuntu16
- Ubuntu 16.04 Xenial Xerus (old LTS)
Each image provides:
- a base Linux OS
- Shaarli PHP dependencies (OS packages)
- test PHP dependencies (OS packages)
- Composer
- Tests that run inside the container using a standard Linux user account (running tests as root
would bypass permission checks and may hide issues)
Build a test image:
# build the Debian 9 Docker image
cd /path/to/shaarli/tests/docker/debian9
docker build -t shaarli-test:debian9 .
Run unit tests in a container:
cd /path/to/shaarli
# install/update 3rd-party test dependencies
composer install --prefer-dist
# run tests using the freshly built image
docker run -v $PWD:/shaarli shaarli-test:debian9 docker_test
# run the full test campaign
docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests