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

Ahoy

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

Docker Compose

docker compose exec cli vendor/bin/phpunit                                        # Run all tests.
docker compose exec cli vendor/bin/phpunit --testsuite=unit                       # Run Unit tests.
docker compose exec cli vendor/bin/phpunit --testsuite=kernel                     # Run Kernel tests.
docker compose exec cli vendor/bin/phpunit --testsuite=functional                 # Run Functional tests.
docker compose exec cli vendor/bin/phpunit --testsuite=functional-javascript      # Run Functional JavaScript tests.

Running all tests in the file

Ahoy

ahoy test-unit path/to/MyTest.php

Docker Compose

docker compose exec cli vendor/bin/phpunit path/to/MyTest.php

Running selected tests by name

Ahoy

ahoy test-unit --filter=MyTest

Docker Compose

docker compose exec cli vendor/bin/phpunit -- --filter=MyTest

Running tagged tests with @group group_name annotation

Ahoy

ahoy test-unit --group=group_name

Docker Compose

docker compose exec cli vendor/bin/phpunit -- --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 continuous integration 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"/>

Chrome session flags

Functional JavaScript tests use a Chrome browser running in the selenium/standalone-chromium container. The following flags are passed via MINK_DRIVER_ARGS_WEBDRIVER in phpunit.xml to ensure stable and deterministic test execution:

Flag	Purpose
--disable-extensions	Prevents interference from browser extensions
--disable-popup-blocking	Allows tests to open popups without being blocked
--disable-translate	Prevents the translation bar from appearing on non-English pages
--force-prefers-reduced-motion	Disables CSS animations and transitions for test stability
--test-type	Suppresses error dialogs and crash recovery prompts
--window-size=1920,1080	Sets a deterministic viewport size for consistent screenshots

The w3c: true option is required for compatibility with Selenium 4.

Bootstrap

The custom tests/phpunit/bootstrap.php file runs before tests to:

1. Set BROWSERTEST_OUTPUT_BASE_URL from the VORTEX_LOCALDEV_URL environment variable so that HTML output links are accessible from the host machine.
2. Create the web/sites/simpletest/browser_output directory required by the HtmlOutputLogger extension before it initializes (see Drupal core issue #2992069).

Coverage

PHPUnit is configured to generate code coverage reports. The reports are stored in .logs/coverage/phpunit/cobertura.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.

Continuous integration pipeline runs tests with coverage by default and stores the reports as artifacts.

Coverage threshold

CI enforces a minimum coverage threshold. If coverage falls below the threshold, the build fails. Set VORTEX_CI_CODE_COVERAGE_THRESHOLD to configure the minimum percentage (default: 90).

PR comments

Coverage reports are posted as PR comments automatically. Each new report replaces the previous one — older comments are minimized to keep the PR timeline clean. The comment includes a header indicating the CI source (GitHub Actions or CircleCI).

Set VORTEX_CI_CODE_COVERAGE_PR_COMMENT_SKIP to 1 to disable.

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 continuous integration pipeline

This tool runs in continuous integration pipeline 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.