Assertions
Everything you check in a MicroUnit test goes through MicroUnit\Assertion\Assert. It is one class with static methods, grouped here by topic: values, numbers and dates, collections, strings and JSON, files, behaviour and snapshots. The names are plain English, the argument order is the one you already know from PHPUnit, and a failure tells you what was expected, what arrived and, where it helps, shows a diff. This page lists every method with its signature, what it checks and a small example. If you have not written a test yet, start with writing tests.
Two rules that cover every method
Expected first, actual last, message at the very end. It is PHPUnit’s order, so muscle memory carries over:
Assert::exact(42, $answer);
Assert::countEquals(3, $cart->items());
Assert::stringStartsWith('INV-', $invoice->number, 'Invoice numbers need the INV- prefix');
The optional $message is printed above the assertion’s own description when it fails. It is always the last parameter, so for methods with optional parameters in between, use a named argument: Assert::contains('2', $ids, message: 'id missing').
Behaviour assertions take the callable first. When the thing under test is “what happens when this code runs”, the code comes first and the expectation follows:
Assert::throws(fn () => $cart->checkout(), EmptyCartException::class);
Assert::prints(fn () => $report->render(), "Total: 3\n");
Loose or strict: equals versus exact
Assert::exact() is ===. Same type, same value, and for objects the same instance. It is the one to reach for by default, because it catches the '42' that should have been 42.
Assert::equals() is loose, and smarter than PHP’s == in one important way: objects of the same class are compared property by property, recursively, like PHPUnit’s assertEquals. Two Money(5, 'EUR') objects are equal even though they are different instances. Dates compare as moments in time, so 12:00 UTC equals 13:00 +01:00. Objects of different classes are never equal. Scalars inside still compare with ==, so 1 equals '1'.
Assert::equals(new Money(5, 'EUR'), $wallet->balance()); // passes for an equal copy
Assert::exact(new Money(5, 'EUR'), $wallet->balance()); // fails: different instance
Assert::equals(1, '1'); // passes
Assert::exact(1, '1'); // fails
My rule of thumb: exact for scalars and anything where the type matters, equals for value objects and arrays of them.
What a failure looks like
Every failed assertion throws a TestFailedException carrying an AssertionFailure: a description, the expected and actual values, an optional diff and your custom message. Value comparisons (equals, exact, equivalent, containsSubset, keysEqual, the string equality checks, matchesFormat, jsonEquals, fileContentEquals, prints and snapshots) render a diff, so a two-hundred-line array points straight at the line that changed:
[✖] stores_roles (0.07ms)
roles changed
Failed asserting that two values are equal.
--- Expected
+++ Actual
@@ @@
'name' => 'Ada' (string),
'roles' => [
0 => 'admin' (string),
- 1 => 'dev' (string),
+ 1 => 'ops' (string),
],
]
The rest print Expected: and Actual: lines. Values always carry their type ('42' (string) versus 42 (int)), because “expected 42, got 42” is the most useless failure message in testing. How results are rendered for terminals, CI and AI agents is covered in output.
Every assertion counts
Each assertion that runs, passing or failing, is counted for the current test: every Assert check once (throws(), fileContains() and a passing eventually() included, plus whatever the blocks of each(), multiple() and eventually() assert inside) and every AssertMock or AssertResponse check once, so AssertMock::begin($mock)->isCalledOnce('send')->isCalledWith('send', [$mail]) counts two. A test that passes without making a single assertion is flagged as risky: the console prints no assertions next to it, and agent output lists it as a warning. A test that cannot fail is not a test, and this is the cheapest way to catch the one where the assertion sits behind an if that never runs.
To make such tests fail the run, enable failOnRiskyTests() on the configuration builder.
Values
equals / notEquals
Assert::equals(mixed $expected, mixed $actual, string $message = ''): void
Assert::notEquals(mixed $unexpected, mixed $actual, string $message = ''): void
Loose comparison, objects of the same class property by property (see above).
Assert::equals(['id' => 1, 'name' => 'Ada'], $user->toArray());
Assert::notEquals($before, $after);
exact / notExact
Assert::exact(mixed $expected, mixed $actual, string $message = ''): void
Assert::notExact(mixed $unexpected, mixed $actual, string $message = ''): void
Strict comparison (===).
Assert::exact(3, $cart->count());
Assert::notExact($original, $clone); // a different instance
isTrue / isFalse / isNull / notNull
Assert::isTrue(mixed $actual, string $message = ''): void
Assert::isFalse(mixed $actual, string $message = ''): void
Assert::isNull(mixed $actual, string $message = ''): void
Assert::notNull(mixed $actual, string $message = ''): void
Strict checks: isTrue(1) fails, only true passes.
Assert::isTrue($user->isActive());
Assert::notNull($repository->find(42));
instanceOf
Assert::instanceOf(string $expectedClass, mixed $actual, string $message = ''): void
The value is an instance of the class or interface. The failure shows the actual type.
Assert::instanceOf(OrderPlaced::class, $events[0]);
isType
Assert::isType(string $expectedType, mixed $actual, string $message = ''): void
Checks a type written the way PHP writes types: int, ?string, int|float, a class, interface or enum name, plus a few extras: list, numeric, scalar, callable, iterable, resource, mixed. An unknown type name throws an InvalidArgumentException instead of silently passing.
Assert::isType('?string', $user->nickname);
Assert::isType('int|float', $metrics['latency']);
Assert::isType('list', $response['items']);
PHPUnit has one method per type (assertIsInt, assertIsString, …) and no way to say “nullable” or “int or float” in one call.
equivalent
Assert::equivalent(mixed $expected, mixed $actual, string $message = ''): void
Same contents, order ignored, recursively: lists are compared as multisets, maps by key. Values inside compare like equals(). Use it for “the same items in any order”, which is what most query results and set-like collections promise.
Assert::equivalent(['admin', 'dev'], $user->roles());
Assert::equivalent(['b' => [2, 1], 'a' => 1], ['a' => 1, 'b' => [1, 2]]); // passes
containsSubset
Assert::containsSubset(array|object $subset, mixed $actual, string $message = ''): void
$actual contains at least the keys of $subset with equal values, recursively. Everything else in $actual is ignored. Works on arrays, stdClass objects (decoded JSON), ArrayAccess objects and public properties. The failure names the missing paths and diffs only the part you asked about.
Assert::containsSubset(['user' => ['name' => 'Ada']], $payload);
Assert::containsSubset(['status' => 'paid'], json_decode($body));
Failed asserting that the value contains the expected subset; missing: user.email.
PHPUnit removed assertArraySubset() in version 9. This is the replacement people kept asking for, and it is the right tool for API responses that carry timestamps and ids you do not care about.
hasProperty
Assert::hasProperty(string $property, object $actual, string $message = ''): void
The object has the property (declared or dynamic, any visibility).
Assert::hasProperty('email', $dto);
Numbers and dates
Comparisons
Assert::isGreaterThan(int|float $minimum, int|float $actual, string $message = ''): void
Assert::isGreaterThanOrEqual(int|float $minimum, int|float $actual, string $message = ''): void
Assert::isLessThan(int|float $maximum, int|float $actual, string $message = ''): void
Assert::isLessThanOrEqual(int|float $maximum, int|float $actual, string $message = ''): void
The bound comes first, like an expected value.
Assert::isGreaterThan(0, $order->total());
Assert::isLessThanOrEqual(100, $progress);
isBetween
Assert::isBetween(int|float $minimum, int|float $maximum, int|float $actual, bool $inclusive = true, string $message = ''): void
Inside the range, bounds included unless inclusive: false.
Assert::isBetween(1, 10, $roll);
Assert::isBetween(0, 1, $probability, inclusive: false);
equalsWithDelta
Assert::equalsWithDelta(int|float $expected, int|float $actual, int|float $delta, string $message = ''): void
Absolute tolerance. The answer to 0.1 + 0.2 !== 0.3.
Assert::equalsWithDelta(0.3, 0.1 + 0.2, 0.0001);
equalsWithinPercent
Assert::equalsWithinPercent(int|float $expected, int|float $actual, int|float $percent, string $message = ''): void
Relative tolerance: equalsWithinPercent(100, $measured, 5) accepts 95 to 105. Better than a delta whenever the scale of the number varies, for timings, sizes and estimates.
Assert::equalsWithinPercent(1_000_000, $estimatedRows, 10);
isNan / isFinite
Assert::isNan(mixed $actual, string $message = ''): void
Assert::isFinite(int|float $actual, string $message = ''): void
isNan passes only for the float NAN. isFinite fails for NAN, INF and -INF.
Assert::isFinite($calculator->ratio($a, $b));
dateEquals
Assert::dateEquals(\DateTimeInterface|string $expected, \DateTimeInterface|string $actual, int|float $toleranceInSeconds = 0, string $message = ''): void
Same moment in time, give or take the tolerance. Strings are parsed like new DateTimeImmutable(), so 'now', '+1 day' and ISO dates all work, and time zones are taken into account. The failure says how far apart the two dates were.
Assert::dateEquals('now', $user->createdAt, toleranceInSeconds: 5);
Assert::dateEquals('2026-01-01 12:00 UTC', '2026-01-01 13:00 +01:00'); // passes
Failed asserting that the dates are equal within 5 s (they differ by 9 s).
This is the assertion I wanted for years. “Created just now” is one of the most common checks there is, and doing it with timestamps and a delta is noise.
Collections
These accept arrays, and where the signature says iterable also generators and other Traversable objects.
empty / notEmpty
Assert::empty(mixed $actual, string $message = ''): void
Assert::notEmpty(mixed $actual, string $message = ''): void
Empty means: an array or Countable without elements, '', null, 0 or false. Unlike PHP’s empty(), the string '0' is not empty.
Assert::empty($validator->errors());
Assert::notEmpty($search->results());
contains / notContains
Assert::contains(mixed $needle, iterable $haystack, bool $strict = true, string $message = ''): void
Assert::notContains(mixed $needle, iterable $haystack, bool $strict = true, string $message = ''): void
The collection has (or lacks) the element. Strict by default; pass strict: false for ==. For substrings, use stringContains.
Assert::contains('admin', $user->roles());
Assert::contains('2', [1, 2, 3], strict: false);
containsAll
Assert::containsAll(array $expected, iterable $actual, bool $strict = true, string $message = ''): void
Every element of $expected is in $actual, in any order. Other elements are allowed.
Assert::containsAll(['admin', 'dev'], $user->roles());
containsOnly
Assert::containsOnly(array $allowedValues, array $actual, string $message = ''): void
Every element of $actual is one of the allowed values (strict). The failure lists the offenders.
Assert::containsOnly(['draft', 'published'], array_column($posts, 'status'));
countEquals / sameSize
Assert::countEquals(int $expected, array|\Countable $actual, string $message = ''): void
Assert::sameSize(array|\Countable $expected, array|\Countable $actual, string $message = ''): void
Assert::countEquals(3, $cart->items());
Assert::sameSize($input, $output);
hasKey / notHasKey
Assert::hasKey(int|string $key, array $actual, string $message = ''): void
Assert::notHasKey(int|string $key, array $actual, string $message = ''): void
Assert::hasKey('id', $row);
Assert::notHasKey('password', $user->toArray());
keysEqual
Assert::keysEqual(array $expectedKeys, array $actual, string $message = ''): void
The array has exactly these keys, in any order. No more, no fewer.
Assert::keysEqual(['id', 'name', 'email'], $user->toArray());
isList
Assert::isList(mixed $actual, string $message = ''): void
An array with keys 0, 1, 2, ... in order. Catches the array_filter() result you forgot to array_values() before json_encode() turned it into an object.
Assert::isList($response['items']);
each
Assert::each(iterable $items, callable $check, string $message = ''): void
Runs $check($item, $key) for every element. The check fails an element by making a failing assertion or by returning false. Every failing element is reported with its key, not only the first one (up to ten are listed in full).
Assert::each($users, fn (User $user) => Assert::isTrue($user->isActive()));
Assert::each($prices, fn (int $price) => $price > 0);
Failed asserting that every element passes; 2 of 4 failed:
[1] 3 is odd
Failed asserting that two values are identical (type and value).
[3] 5 is odd
Failed asserting that two values are identical (type and value).
PHPUnit has assertContainsOnly() for types and a foreach loop for everything else, which stops at the first bad element.
isUnique
Assert::isUnique(iterable $actual, string $message = ''): void
No element appears twice. Strict, so 1 and '1' are different; objects are compared by identity. The failure lists the duplicates.
Assert::isUnique(array_column($orders, 'number'));
isSorted
Assert::isSorted(iterable $actual, ?callable $by = null, bool $descending = false, string $message = ''): void
Elements are in ascending order (or descending), compared with <=>. Equal neighbours are fine. Pass by: to sort by a derived value. The failure names the first element that is out of order.
Assert::isSorted($leaderboard->scores(), descending: true);
Assert::isSorted($posts, by: fn (Post $post) => $post->publishedAt, descending: true);
Strings and JSON
stringContains / stringNotContains
Assert::stringContains(string $needle, string $haystack, string $message = ''): void
Assert::stringNotContains(string $needle, string $haystack, string $message = ''): void
Assert::stringContains('Welcome, Ada', $html);
Assert::stringNotContains('Exception', $log);
stringContainsIgnoringCase
Assert::stringContainsIgnoringCase(string $needle, string $haystack, string $message = ''): void
Case-insensitive, multibyte-aware when mbstring is available.
Assert::stringContainsIgnoringCase('error', $output);
stringStartsWith / stringEndsWith
Assert::stringStartsWith(string $prefix, string $actual, string $message = ''): void
Assert::stringEndsWith(string $suffix, string $actual, string $message = ''): void
Assert::stringStartsWith('INV-', $invoice->number);
Assert::stringEndsWith('.pdf', $attachment->filename);
matchesRegex
Assert::matchesRegex(string $pattern, string $actual, string $message = ''): void
An invalid pattern throws an InvalidArgumentException instead of failing quietly.
Assert::matchesRegex('/^\d{4}-\d{2}-\d{2}$/', $date);
matchesFormat
Assert::matchesFormat(string $format, string $actual, string $message = ''): void
Matches text with placeholders, the format PHP’s own .phpt tests use (PHPUnit’s assertStringMatchesFormat() speaks the same language). Much easier to read than a regex when output contains timestamps, paths or ids. Line endings are normalised, and a failure is shown as a line diff.
| Placeholder | Matches |
|---|---|
%s |
one or more characters on one line |
%S |
the same, or nothing |
%a |
one or more characters, across lines |
%A |
the same, or nothing |
%d |
digits |
%i |
a signed integer |
%f |
a float |
%x |
hexadecimal digits |
%c |
a single character |
%w |
optional whitespace |
%e |
the directory separator |
%% |
a literal % |
Assert::matchesFormat("Saved order %d at %s\n", $output);
Assert::matchesFormat("id: %x, took %fms%A", $log);
equalsIgnoringCase
Assert::equalsIgnoringCase(string $expected, string $actual, string $message = ''): void
Assert::equalsIgnoringCase('Ada Lovelace', $user->name);
equalsIgnoringWhitespace
Assert::equalsIgnoringWhitespace(string $expected, string $actual, string $message = ''): void
Equal after trimming both strings and collapsing every run of whitespace (spaces, tabs, newlines) into one space. Made for SQL, HTML and generated code where the indentation is not what you are testing. Note that whitespace is collapsed, not removed: <ul><li> and <ul> <li> are still different.
Assert::equalsIgnoringWhitespace('SELECT * FROM users WHERE id = 1', $query->toSql());
PHPUnit has no equivalent; you end up writing the preg_replace yourself.
isJson
Assert::isJson(string $actual, string $message = ''): void
The string is valid JSON. The failure includes the parser’s error.
Assert::isJson($response->body);
jsonEquals
Assert::jsonEquals(mixed $expected, string $actualJson, string $message = ''): void
Same JSON document. Object key order and formatting are ignored; list order and types are not, so 1, 1.0 and "1" are three different values. $expected can be a JSON string or the PHP value it should decode to, which saves you from writing JSON inside PHP strings. The failure is a diff of both documents, pretty-printed with sorted keys.
Assert::jsonEquals(['id' => 7, 'tags' => ['a', 'b']], $response->body);
Assert::jsonEquals('{"b": 2, "a": 1}', '{"a":1,"b":2}'); // passes
Files
Assert::fileExists(string $path, string $message = ''): void
Assert::fileNotExists(string $path, string $message = ''): void
Assert::directoryExists(string $path, string $message = ''): void
Assert::fileContains(string $needle, string $path, string $message = ''): void
Assert::fileContentEquals(string $expected, string $path, string $message = ''): void
fileExists wants a regular file, directoryExists a directory; fileNotExists fails if anything exists at the path. fileContains and fileContentEquals first check that the file exists and is readable. fileContentEquals normalises line endings on both sides, so a test written on Linux passes against a file generated on Windows, and shows a line diff on failure.
$exporter->export($dir);
Assert::fileExists("$dir/report.csv");
Assert::fileContains('Total;3', "$dir/report.csv");
Assert::fileContentEquals("Total: 3\nDone\n", "$dir/summary.txt");
Pair them with TemporaryDirectory from the integration testing toolkit, so every test gets a clean directory that is deleted afterwards.
Behaviour
throws
Assert::throws(callable $callable, ?string $expectedType = null, ?string $expectedMessage = null, string $message = ''): \Throwable
The callable throws. Optionally of a type (subclasses count) and with a message that contains $expectedMessage. It returns the caught exception, so you can assert on its details right after. No expectException() that has to come before the code and silently swallows the rest of the test.
$exception = Assert::throws(fn () => $stock->reserve('A1', 5), OutOfStock::class, 'out of stock');
Assert::exact('A1', $exception->sku);
Failed asserting that the thrown exception is of type OutOfStock.
Expected: 'OutOfStock' (string)
Actual : 'LogicException: nope' (string)
doesNotThrow
Assert::doesNotThrow(callable $callable, string $message = ''): mixed
Runs the callable and returns its result. If it throws, the test fails with a clear “no exception expected” message that includes the exception’s class, message, file and line, instead of ending as an error. It also counts as an assertion, so “this does not blow up” is a legitimate, non-risky test.
$order = Assert::doesNotThrow(fn () => $importer->import($legacyCsv));
Assert::exact(120, $order->lineCount());
triggersError
Assert::triggersError(callable $callable, int $level = E_ALL, ?string $expectedMessage = null, string $message = ''): string
The callable triggers a PHP warning, notice or deprecation of $level, optionally with a message containing $expectedMessage. It returns the message. The error is captured, so it neither prints nor reaches other error handlers.
Assert::triggersError(fn () => $legacy->run(), E_USER_DEPRECATED, 'use runNew() instead');
PHPUnit 10 removed expectWarning(), expectDeprecation() and friends. Deprecations are exactly what you want to test when you maintain a library, so this one stays.
prints
Assert::prints(callable $callable, string $expected, string $message = ''): void
The callable prints exactly $expected (via echo, print, printf and so on). Scoped to the callable, unlike PHPUnit’s expectOutputString(), which applies to the whole test.
Assert::prints(fn () => $command->run(['--dry-run']), "Would delete 3 files\n");
eventually
Assert::eventually(callable $check, float $timeoutInSeconds = 5.0, float $intervalInSeconds = 0.1, string $message = ''): mixed
Retries $check until it passes (no failed assertion, no exception, not false) or the timeout runs out, then reports the last failure and how many attempts were made. It returns whatever the check returned. For queues, background workers, servers, file watchers and anything else that becomes true a moment later. Much better than a sleep(2) that is too long on your machine and too short on CI.
Assert::eventually(fn () => Assert::notNull($mailbox->latest()), timeoutInSeconds: 3);
$job = Assert::eventually(function () use ($queue, $id) {
$job = $queue->find($id);
Assert::isTrue($job?->isDone());
return $job;
});
Assertions return nothing, so when you need the value afterwards, return it from the closure yourself, as in the second example.
Failed asserting that the check passes within 0.3 s (4 attempts). Last failure:
Failed asserting that two values are identical (type and value).
multiple: soft assertions
Assert::multiple(callable $assertions, string $message = ''): void
Runs every Assert call in the block even when some fail, then reports all failures together. One run shows everything that is wrong with a result, instead of fix, rerun, fix, rerun.
Assert::multiple(function () use ($user) {
Assert::exact('Ada', $user->name);
Assert::exact('ada@example.com', $user->email);
Assert::isTrue($user->active);
});
2 assertions failed:
1) Failed asserting that two values are identical (type and value).
Expected: 'Ada' (string)
Actual : 'Grace' (string)
2) Failed asserting that value is true.
Expected: true (bool)
Actual : false (bool)
Blocks nest, and each() and eventually() work inside them. Assert, AssertMock and AssertResponse checks are all collected softly. A few things end the block at their failure (which is still reported, together with the failures before it): fail(), throws() when nothing is thrown and triggersError() when nothing is triggered, because they cannot carry on without a result, and custom assertions that throw TestFailedException themselves.
skip / skipIf / fail
Assert::skip(string $reason = 'Skipped.'): never
Assert::skipIf(bool $condition, string $reason): void
Assert::fail(string $message = 'Test failed.'): never
Not assertions in the strict sense, but they live here. Skipped tests show up as skipped with their reason, never as passed.
Assert::skipIf(!extension_loaded('pdo_pgsql'), 'pdo_pgsql missing');
Assert::fail('Not implemented yet');
Snapshots
Assert::matchesSnapshot(mixed $actual, ?string $name = null, string $message = ''): void
Compares a value with a stored copy next to the test file. The first run writes it, later runs fail on any difference, and --update-snapshots accepts intended changes. Built in, no plugin needed (PHPUnit needs a separate package for this).
Assert::matchesSnapshot($invoice->renderHtml());
Where snapshots live, how CI treats them and when they are a bad idea: snapshots.
Fluent assertions
If you prefer chaining several checks on one value, there are four small fluent classes. Each starts with begin($actual) and returns itself from every method. They call the same Assert methods underneath, so failures, messages and assertion counting are identical.
AssertSingle::begin($user->id)->notNull()->exact(42);
AssertNumeric::begin($total)->isGreaterThan(0)->isLessThanOrEqual(1000);
AssertArray::begin($row)->hasKey('id')->notHasKey('password')->countEquals(3);
AssertString::begin($slug)->startsWith('post-')->matchesRegex('/^[a-z0-9-]+$/');
| Class | Methods |
|---|---|
AssertSingle (any value) |
equals, notEquals, exact, notExact, instanceOf, isTrue, isFalse, isNull, notNull |
AssertNumeric (int\|float) |
equals, exact, notExact, equalsWithDelta($expected, $delta), isGreaterThan, isGreaterThanOrEqual, isLessThan, isLessThanOrEqual, isBetween($min, $max, $inclusive = true) |
AssertArray (array) |
equals, notEquals, exact, notExact, empty, notEmpty, contains($needle, $strict = true), notContains, countEquals, hasKey, notHasKey, keysEqual, containsOnly |
AssertString (string) |
equals, contains, notContains, startsWith, endsWith, matchesRegex, lengthEquals, isEmpty, notEmpty |
Every method takes the expected value (if any) and an optional $message last. Two details worth knowing: AssertString::equals() is strict (===), and AssertString::lengthEquals() counts UTF-8 characters, not bytes, even without mbstring.
The fluent classes cover the common checks only. For everything else, use Assert directly. Both styles mix freely in one test.
HTTP responses: AssertResponse
AssertResponse asserts on HTTP responses fluently, whichever library produced them:
AssertResponse::begin($response)
->statusIs(201)
->headerIs('Location', '/products/A1')
->jsonPathEquals('data.sku', 'A1');
begin() accepts:
| Response | Recognised by |
|---|---|
MicroUnit’s HttpResponse (from Http::get(), Http::post(), …) |
its class |
| PSR-7 responses (Guzzle, Nyholm, Laminas, …) | getStatusCode() and getHeaderLine() |
Symfony Response (HttpFoundation) |
getStatusCode() and getContent() |
Laravel TestResponse |
its baseResponse (a Symfony response) |
CodeIgniter TestResponse |
its class; the wrapped response is read |
Anything else throws an InvalidArgumentException naming the class it got. No package is required: the types are detected by duck typing.
| Method | Checks |
|---|---|
statusIs(int $expected) |
exact status code |
isOk() |
any 2xx status |
isNotFound() |
status 404 |
isRedirect(?string $location = null) |
a 3xx status, and the exact Location header when given |
headerIs(string $name, string $expected) |
the header’s value equals $expected |
headerContains(string $name, string $needle) |
the header exists and contains $needle |
bodyContains(string $needle) |
the body contains the text |
bodyEquals(string $expected) |
the body equals the text exactly |
jsonEquals(mixed $expected) |
the decoded JSON body equals $expected (loose comparison, object key order irrelevant) |
jsonPathEquals(string $path, mixed $expected) |
the value at a dot path equals $expected strictly: 'data.items.0.id' |
jsonHasPath(string $path) |
the dot path exists in the JSON body |
Every method takes an optional $message as last argument. Header names are case-insensitive. A body that is not valid JSON fails the JSON methods with a clear message rather than a JsonException. Every failure includes the start of the response body, because “expected 200, got 500” is only half the story:
Failed asserting that the response is successful (2xx).
Response body: {"error":"boom"}
Expected: '2xx' (string)
Actual : 500 (int)
Mind the difference between the two JSON checks: jsonEquals() compares loosely, jsonPathEquals() strictly, so jsonPathEquals('data.id', 42) fails when the API returns "42". For more on testing applications over HTTP, see integration testing and frameworks.
Custom assertions
A custom assertion is a function that throws MicroUnit\Exceptions\TestFailedException with a MicroUnit\Assertion\AssertionFailure when the check fails. Before you write one, see if it can be built from existing assertions; then you get the messages, diffs and counting for free:
function assertValidIban(string $iban, string $message = ''): void
{
Assert::matchesRegex('/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/', $iban, $message);
}
When you need your own failure, build it yourself:
use MicroUnit\Assertion\AssertionFailure;
use MicroUnit\Core\TestContext;
use MicroUnit\Exceptions\TestFailedException;
function assertIsEven(int $actual, string $message = ''): void
{
TestContext::countAssertions();
if ($actual % 2 !== 0) {
throw new TestFailedException(new AssertionFailure(
'Failed asserting that the number is even.',
expected: 'an even number',
actual: $actual,
customMessage: $message,
));
}
}
AssertionFailure takes the description, the expected and actual values (both optional: leave them out and no Expected: / Actual: lines are printed), an optional MicroUnit\Helpers\Diff (Diff::generate($expected, $actual) for values, Diff::fromLines($expectedLines, $actualLines) for text) and your custom message. TestContext::countAssertions() tells MicroUnit an assertion ran, so a test that only uses your assertion is not reported as risky.
One limitation: a custom assertion that throws directly ends an Assert::multiple() block at its failure instead of being collected with the others.
Failures from PHPUnit assertions (Laravel’s and Symfony’s test helpers assert through PHPUnit when it is installed) are translated into MicroUnit failures automatically, diff included. See frameworks.
Coming from PHPUnit
Most assertions map one to one; microunit migrate does the translation for you (see migrating from PHPUnit). These are the ones PHPUnit does not have or makes awkward:
| MicroUnit | In PHPUnit |
|---|---|
equivalent |
assertEqualsCanonicalizing comes closest |
containsSubset |
assertArraySubset was removed in PHPUnit 9 |
isType('?int'), isType('int\|float') |
one method per type, no nullable or union types |
each |
a foreach that stops at the first failure |
isUnique, isSorted |
write it yourself |
equalsWithinPercent |
only absolute deltas |
dateEquals |
compare timestamps with a delta |
equalsIgnoringWhitespace |
normalise both strings yourself |
jsonEquals with a PHP array |
expects two JSON strings |
fileContentEquals |
compares raw bytes, line endings included |
throws returning the exception |
expectException() before the code, no access to the exception |
doesNotThrow |
call the code and expectNotToPerformAssertions() |
triggersError |
expectWarning() and friends were removed in PHPUnit 10 |
prints |
expectOutputString() applies to the whole test |
eventually |
sleep() and hope |
multiple |
no soft assertions |
matchesSnapshot |
needs a third-party package |