Helpers to work with PHPUnit

🧩 Features

📋 Requirements

• PHP 8.3 or newer
• PHPUnit 11.4 through PHPUnit 13
• Symfony 6.4, or Symfony 7.2 through Symfony 8

Two traits need a package that this library does not require itself, so add it to your own project when you use them:

📦 Installation

composer require --dev alexskrypnyk/phpunit-helpers

🚀 Usage

This package provides a collection of traits that can be used in your PHPUnit tests to make testing easier. Below is a description of each trait and how to use it.

UnitTestCase

The UnitTestCase class is the base class for unit tests. It includes the ReflectionTrait and LocationsTrait to provide useful methods for testing.

setUp() initialises the test locations and tearDown() removes the workspace directory again. The workspace is kept when the test failed or errored, or when debug mode is on, so the produced files can be inspected.

The class also provides an info() method that collects additional information about the test from methods whose name ends with Info. Methods containing test in their name are excluded to avoid conflicts with test methods. The collected information is also appended to the message of any failing assertion, so a failure report carries the test's context without any extra call. Appending relies on a hook that PHPUnit added in 12.5.24; on earlier versions info() still works but failure messages are left untouched.

Debug mode is enabled by the DEBUG environment variable or the --debug argument, and is readable with UnitTestCase::isDebug():

DEBUG=1 vendor/bin/phpunit

AssertArrayTrait

The AssertArrayTrait provides custom assertions for arrays.

ApplicationTrait

The ApplicationTrait provides methods to test Symfony Console applications and their commands with comprehensive assertions.

EnvTrait

The EnvTrait helps manage environment variables during tests. Every method is static, so it is also usable from data providers.

LocationsTrait

The LocationsTrait provides methods to manage file system locations during tests. It maintains a set of predefined directories as static properties, so they are also reachable from data providers.

ProcessTrait

The ProcessTrait provides methods to run command line processes and assert on their output and exit codes. It integrates with the Symfony Process component for safe and controlled command execution.

SerializableClosureTrait

The SerializableClosureTrait makes closures serializable so they can be used in data providers. It works with both traditional closures and arrow functions, and requires the laravel/serializable-closure package.

ReflectionTrait

The ReflectionTrait provides methods to access and manipulate protected or private members of classes or objects.

TuiTrait

The TuiTrait provides constants and methods for interacting with a Textual User Interface (TUI) during tests, handling keystroke simulation and input entries. It supports both full-string input and character-by-character input simulation.

A "keystroke" is a single key or special key, while an "entry" is one or more keystrokes forming a complete input.

StringTrait

The StringTrait provides the assertStringContainsOrNot() assertion used by the ApplicationTrait and ProcessTrait prefix assertions. Four single-character prefixes control how each expected value is matched:

+ and - compare the value against the whole haystack, not against a word inside it, so they are only useful for short, single-line strings.

There are two modes. In shortcut mode no value carries a prefix and all of them are treated as "substring present". In mixed mode at least one value carries a prefix, and then every value must carry one.

All four prefixes must be single, unique characters, and a value that is empty after its prefix is stripped raises a RuntimeException.

LoggerTrait

The LoggerTrait provides a hierarchical logging system for test debugging, with step tracking, timing and nested workflows. Output is written to STDERR and is suppressed unless verbose mode is enabled, so the default test output stays clean.

Available logging methods:

• log(string) - basic message logging
• logSection(string, ?string, bool, int) - bordered section with an optional double border and a minimum width
• logFile(string, ?string) - file contents between section borders
• logStepStart(?string) - begin step tracking, naming the step after the calling method
• logStepFinish(?string) - end step tracking and record the elapsed time
• logSubstep(string) - indented substep message
• logNote(string) - indented note message
• logStepSummary(string) - return the step summary table, indenting nested steps by the given string, which defaults to two spaces
• logInfo() - the step summary under a heading, collected by UnitTestCase::info()
• logSetVerbose(bool) - enable or disable output
• logSetOutputStream(resource|null) - set the output stream, or NULL for STDERR

Example step summary output:

Using multiple traits

Traits can be combined in a single test class:

Or extend UnitTestCase, which already includes the LocationsTrait and ReflectionTrait:

Every trait declares @mixin \PHPUnit\Framework\TestCase, so it must be used inside a PHPUnit test class.

🤝 Contributing

See CONTRIBUTING.md for local development setup and the linting and testing commands.

🔄 Updating

To pull the latest infrastructure from the template into this project, ask Claude Code to "update scaffold" - see AGENTS.md for details.

This repository was created using the Scaffold project template