Download the PHP package zenstruck/assert without Composer

zenstruck/assert

This library allows dependency-free test assertions. When using a PHPUnit-based test library (PHPUnit itself, Pest, Codeception), failed assertions are automatically converted to PHPUnit failures and successful assertions are added to PHPUnit's successful assertion count.

This library differs from other popular assertion libraries (webmozart/assert & beberlei/assert) in that it is purely for test assertions opposed to what these libraries provide: type safety assertions.

With the exception of the Expectation API (specifically, the Throws Expectation which provides a nice API for making exception assertions), this library is really only useful for 3rd party libraries that would like to provide test assertions but not have a direct dependency on a specific test library.

Installation

Zenstruck\Assert

This is the main entry point for making assertions. When the methods on this class are called, they throw a Zenstruck\Assert\AssertionFailed on failure. If they do not throw this exception, they are considered successful.

When using a PHPUnit-based framework, failed assertions are auto-converted to PHPUnit test failures and successful assertions are added to PHPUnit's successful assertion count.

True/False Assertions

Generic Fail/Pass

Try

Attempt to run a callback and return the result. If an exception is thrown while running, a fail is triggered. If run successfully, a pass is triggered.

Run Assertions

Assert::run() executes a callable. A successful execution is considered a pass and if Zenstruck\Assert\AssertionFailed is thrown, it is a fail.

Expectation API

While the above assertions can be used to create any assertion, a simple, fluent, readable, expectation API is provided. This API is heavily inspired by Pest PHP.

Type Expectations

Throws Expectation

This expectation provides a nice API for exceptions. It is an alternative to PHPUnit's expectException() which has the following limitations:

1. Can only assert 1 exception is thrown per test.
2. Cannot make assertions on the exception itself (other than the message).
3. Cannot make post-exception assertions (think side effects).

Fluent Expectations

AssertionFailed Exception

When triggering a failed assertion, it is important to provide a useful failure message to the user. The AssertionFailed exception has some features to help.

NOTES:

1. When the message is constructed with context, non-scalar values are run through get_debug_type() and strings longer than 100 characters are trimmed. The full context is available via AssertionFailed::context().
2. When using with PHPUnit, the full context is exported with the failure message if in verbose-mode (--verbose|-v).

Assertion Objects

Since Zenstruck\Assert::run() accepts any callable, complex assertions can be wrapped up into invokable objects:

Negatable Assertion Objects

Zenstruck\Assert has a not() method that can be used with Negatable Assertion Objects. This can be helpful to create custom assertions that can be easily negated. Let's convert the example above into a Negatable Assertion Object: