# 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:

- `alpine316` - Alpine Linux 3.16
- `debian8` - 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

GitHub « Previous Next »