Run tests

This page describes how to run tests.

---

Running tests (CLI)

The Unitary CLI is the fastest way to execute and inspect tests. When launched without arguments, it automatically discovers all test groups in your project and runs them:

php vendor/bin/unitary

Same as php vendor/bin/unitary run or php vendor/bin/unitary test

For help and a full list of available flags:

php vendor/bin/unitary --help

Create a boilerplate code to get started quickly:

php vendor/bin/unitary template

Limit output to only failing validations:

php vendor/bin/unitary --errors-only

You can also rerun a specific test by hash:

php vendor/bin/unitary --show=12e65ed93cd2ac5de824254d2c69dc5d0

Response

You can also rerun a specific test by a specified name:

php vendor/bin/unitary --show=unitary

Response

Se Configure test groups for more information on how this actually works below.

Targeting specific tests

Unitary is extremely fast and can execute more tests than you could ever write in under a second. You’ll rarely use --path, --exclude, or --smart-search for performance reasons — they’re mainly for convenience, such as IDE integrations or when you want to limit discovery to specific folders.

During active development, the --show flag is often the more practical choice. It lets you target individual tests by name or hash while still surfacing fatal errors from unrelated test files, errors that would otherwise remain hidden if discovery were narrowly filtered.

php vendor/bin/unitary --path="tests/integration"
php vendor/bin/unitary --exclude="tests/legacy/*"
php vendor/bin/unitary --smart-search

These flags are ideal for quick, local runs. If you want the same behavior every time, define it in your configuration file instead.

---

Configure test groups

Every individual groups can define their own configuration using TestConfig. This allows naming, skipping, or scoping tests directly in code without affecting the rest of the suite.

$config = TestConfig::make()->withName("unitary")->withSkip();

group($config->withSubject("HTTP Request"), function(TestCase $case) {

});

group($config->withSubject("Test mocking library"), function(TestCase $case) {

});

Execute

php vendor/bin/unitary --show=unitary

Response

---

JUnit XML Output (CI-Friendly)

For CI systems and test aggregators, Unitary can emit results as JUnit XML.

Run tests with:

php vendor/bin/unitary --type=junit

This switches the output format from human-readable CLI output to machine-readable XML.

---

Full option reference

Each option listed below can be used as a CLI flag or as a key in the configuration file. They share the same names, accepted types, and default values.

Key	Description	Accepted Values	Default
discover-pattern	Overrides default discovery behavior with directory names or filename patterns.	false, string	false
verbose	Displays warnings and extended diagnostic output.	bool	false
show	Runs a specific test or group by its name or hash (CLI: show=<hash|name>).	string, false	false
errors-only	Hides successful tests and only shows failed or invalid results.	bool	false
type	The expected response type (default, junit, xml).	false, string	false
fail-fast	Stops test execution immediately if error occurs or throws an exception.	bool	false
always-show-files	Always displays the full file path, even for passing tests.	bool	false
smart-search	Enables recursive searching from the defined path upwards until valid test files are found.	bool	false
path	Where Unitary should start to look for test files. Both absolute and relative paths will work.	false, string, array<int, string>	false
exclude	Defines files or directories to skip during discovery.	false, string, array<int, string>	false
timezone	Sets the default timezone for all test executions.	string (valid timezone)	'UTC'
locale	Defines the locale for formatted outputs such as date strings.	string (e.g. en_US, sv_SE)	'en_US'

---

Layer interaction

Unitary merges configuration from all sources in a fixed order:

1. File — base project defaults (unitary.config.php)
2. Code — per-group settings defined through TestConfig
3. CLI — temporary overrides applied last

This predictable precedence makes it easy to test locally with CLI flags while keeping stable project-wide defaults under version control.