Assertions

Previous Next

Assertions are the actual checks inside a test method — the lines that decide whether the test passes or fails. A test method can contain as many assertions as it needs; as long as every single one of them holds true, PHPUnit reports the test as passing. If even one assertion fails, the whole test fails.

Common Assertions Reference

Assertion	What it checks
`assertEquals($expected, $actual)`	Values are loosely equal (`==`) — type differences like `5` vs `"5"` are allowed
`assertSame($expected, $actual)`	Values are identical (`===`) — both value and type must match
`assertTrue($value)` / `assertFalse($value)`	Value is exactly boolean `true` / `false`
`assertNull($value)`	Value is exactly `null`
`assertCount($count, $countable)`	An array or `Countable` has exactly `$count` items
`assertContains($needle, $haystack)`	An array (or iterable) contains the given value
`assertInstanceOf($class, $object)`	An object is an instance of the given class or interface

assertEquals vs assertSame

This is the pair that trips up newcomers most often. assertEquals() uses loose comparison, so assertEquals(5, "5") passes because PHP considers 5 == "5" true. assertSame() uses strict comparison, so assertSame(5, "5") fails — the types don't match, even though the values look alike. Prefer assertSame() whenever the exact type matters, and reach for assertEquals() when only the value matters (for example, comparing two objects for equal property values, or two arrays with the same contents).

Worked Example

A single test method can combine several assertions to check different aspects of a result:

<?php
use PHPUnit\Framework\TestCase;

class UserRepositoryTest extends TestCase
{
    public function testFindAllReturnsUsers()
    {
        $repository = new UserRepository();
        $users = $repository->findAll();

        // There should be exactly 3 users
        $this->assertCount(3, $users);

        // Each one should be a real User object
        $this->assertInstanceOf(User::class, $users[0]);

        // A known user should be in the results
        $this->assertContains('sonu@example.com', $repository->emails());

        // findAll() should never return null
        $this->assertFalse(is_null($users));

        // The id of the first user must match exactly (type and value)
        $this->assertSame(1, $users[0]->id);
    }
}

If findAll() ever returns 2 users instead of 3, or the wrong type creeps into id, this single test method catches it — no separate test method is required per assertion.

Note: This is real, correct PHPUnit code meant to be copied into your own project — this website's codebase has no PHPUnit installed, so nothing here runs live on this page.

Reading a Failure Diff

When an assertion fails, PHPUnit doesn't just say "failed" — it prints a diff comparing what it expected against what it actually got, which is usually enough to spot the bug immediately without adding your own debug output.

Next steps: Head to Test Lifecycle to learn how setUp() and tearDown() give every test a clean starting point.

Previous Next