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:

  • . - success
  • F - 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 &

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:

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