DUnit

DUnit (dee-unit) makes your life easier by allowing you to test your PHP code against multiple Docker containers. This allows for testing your code against different versions of PHP or against different PHP configurations. By default, DUnit can perform a syntax check against your whole repository and run a PHPUnit test suite.

Default Containers

DUnit includes preconfigured containers for the following PHP versions:

• PHP 5.2 (add vectorface/php5.2 to your .dunitconfig)
• PHP 5.3
• PHP 5.4
• PHP 5.5
• PHP 5.6
• PHP 7.0-dev (add vectorface/php-nightly to your dunitconfig)
• HHVM stable
• HHVM nightly (add vectorface/hhvm-nightly to your .dunitconfig)

and has the following native extensions installed:

• apc (apcu on PHP 5.5 and newer)
• curl
• gd
• intl (PHP 5.3 and newer)
• json
• mcrypt

Installation

Simply run the following composer command:

$ composer require vectorface/dunit --dev

It is highly recommended to copy the example config to your project root to control the default behaviour of the dunit command.

$ cp ./vendor/vectorface/dunit/dunitconfig.example ./.dunitconfig

And edit the file .dunitconfig to suit your tastes.

Usage

# run PHP syntax checks and your test suite against all supported version of PHP
$ ./vendor/bin/dunit

# show the help documentation
$ ./vendor/bin/dunit -h

# specify a custom configuration file
$ ./vendor/bin/dunit -c "path/.dunitconf"

# explictly specify which containers to use
$ ./vendor/bin/dunit -i "vectorface/php5.3 vectorface/php5.4"

Configuration

There are three ways to customize the dunit command:

• Environment variables
• Local config file
• Script flags.

Environment variables

The following environment variables can be set to configure dunit.

• DUNIT_IMAGES - a string like "vectorface/php5.3 vectorface/php5.4" which indicates the list of images to run against.
• DUNIT_PHPSYNTAX - a true/false flag indicating whether dunit should run the syntax checks.
• DUNIT_PHPSYNTAXCOMMAND - a string indicating the exact command dunit should run to perform the syntax checks. This variable is ignored if DUNIT_PHPSYNTAX is set to false. Note that the command runs inside the Docker container and not on your host machine.
• DUNIT_PHPUNIT - a true/false flag indicating whether dunit should run PHPUnit.
• DUNIT_PHPUNITCOMMAND - a string indicating the exact command dunit should execute for the unit test suite. This variable is ignored if DUNIT_PHPUNIT is set to false. Note that the command runs inside the Docker container and not on your host machine.

Examples:

Run dunit for versions 5.3 and 5.4 of PHP and skip the syntax check:

$ DUNIT_IMAGES="vectorface/php5.3 vectorface/php5.4" DUNIT_PHPSYNTAX=false ./vendor/bin/dunit

Local config file (.dunitconfig)

The dunit script will check for the presence of a local file named .dunitconfig. An example config file can be copied from the composer package:

$ cp ./vendor/vectorface/dunit/dunitconfig.example ./.dunitconfig

The environment variables specified by the config file will override any variables passed directly to the script.

Script flags

The dunit script can also take a number of flags. These flags will always override conflicting environment variable settings.

• -h - displays help information.
• -c ./path/to/config - dunit will use the config located at the provided path instead of looking in your local folder for .dunitconfig.
• -i "image1 image2" - dunit will only run against the specified images.
• --version - displays the current version.
• -p - pulls the latest version of all the docker images

Examples:

Run dunit for versions 5.3 and 5.4 of PHP.

$ ./vendor/bin/dunit -i "vectorface/php5.3 vectorface/php5.4"

Run dunit with a custom config file.

$ ./vendor/bin/dunit -c ../dunit.global.conf

Upgrading from 1.x to 2.x

The .dunitconfig syntax has changed entirely from version 1 to version 2 so it is required that you copy the new config file in place.

$ cp ./vendor/vectorface/dunit/dunitconfig.example ./.dunitconfig

and adjust your config accordingly.

Also note that DUnit no longer supports the environment variables DUNIT_PHPVERSION and DUNIT_DOCKERIMAGE. These variables have been merged as the variable DUNIT_IMAGES.

Similarly, the flag -p has been replaced by -i.