PHPUnit – The PHP Testing Framework

https://github.com/sebastianbergmann/phpunit/

PHPUnit is a programmer-oriented testing framework for PHP.

Vortex comes with pre-configured PHPCS ruleset for Drupal projects.

Usage

vendor/bin/phpunit                          # Run all tests.
vendor/bin/phpunit --testsuite=unit         # Run Unit tests.
vendor/bin/phpunit --testsuite=kernel       # Run Kernel tests.
vendor/bin/phpunit --testsuite=functional   # Run Functional tests.

or

ahoy test-unit                              # Run Unit tests.
ahoy test-kernel                            # Run Kernel tests.
ahoy test-functional                        # Run Functional tests.

Running all tests in the file

vendor/bin/phpunit path/to/MyTest.php

or

ahoy test-unit path/to/MyTest.php

Running selected tests by name

vendor/bin/phpunit --filter=MyTest

or

ahoy test-unit --filter=MyTest

Running tagged tests with @group group_name annotation

vendor/bin/phpunit --group=group_name

or

ahoy test-unit --group=group_name

Configuration

See configuration reference.

All global configuration takes place in the phpunit.xml file.

By default, PHPUnit will run tests for custom modules and themes, Drupal settings and CI configuration.

The recommended way to adding test targets is via using test suites:

<testsuite name="unit">
  <directory>my/custom/dir/*/tests</directory>
</testsuite>

Run checks against platform version specified in composer.json key config.platform.php:

<config name="testVersion" value="8.1"/>

Coverage

PHPUnit is configured to generate code coverage reports. The reports are stored in .logs/test_results/phpunit/phpunit.xml as Cobertura XML, suitable for automated coverage assessment, and in .logs/coverage/phpunit/.coverage-html as HTML coverage report, useful for visual report assessment during test development.

The tests need to run with XDEBUG_MODE=coverage environment variable set.

XDEBUG_MODE=coverage cli vendor/bin/phpunit

CI runs tests with coverage by default and stores the reports as artifacts.

Ignoring lines from coverage

Sometimes it is necessary to ignore lines from coverage. For example, when testing a module that uses a third-party library, it is not necessary to test the library itself.

To ignore a method from coverage, add @codeCoverageIgnore annotation to the method docblock.

/**
 * @codeCoverageIgnore
 */
public function myMethod() {
  // ...
}

To ignore a line from coverage, add @codeCoverageIgnoreStart and @codeCoverageIgnoreEnd annotations before the first and after the last line.

// @codeCoverageIgnoreStart
$a = 1;
$b = 2;
// @codeCoverageIgnoreEnd

Ignoring fail in CI

This tool runs in CI by default and fails the build if there are any violations.

Set VORTEX_CI_PHPUNIT_IGNORE_FAILURE environment variable to 1 to ignore failures. The tool will still run and report violations, if any.