Writing Assertions

A billing test goes green in review and the same calculation ships a string where an integer belongs. The test was green because it asked the wrong question.

$this->assertEquals(1200, $cart->total());  // passes for 1200, "1200", and 1200.0
$this->assertSame(1200, $cart->total());    // passes only for int 1200

assertSame checks value and type with ===; assertEquals compares loosely with == and then recurses through the structure with Sebastian Bergmann's comparator — objects are compared attribute by attribute, floats by value, DateTimeInterface by instant. Neither is "the strict one you should always use"; they answer different contract questions.

Two traps live in the loose path.

Floating point. 0.1 + 0.2 evaluates to 0.30000000000000004, so both assertSame(0.3, 0.1 + 0.2) and assertEquals(0.3, 0.1 + 0.2) fail — == applies no tolerance. assertEquals used to take a $delta argument; it was removed, and assertEqualsWithDelta is the supported spelling:

$this->assertEqualsWithDelta(0.3, 0.1 + 0.2, 1e-9);

Version-dependent comparison rules. PHP 8 changed how numbers compare against non-numeric strings: on PHP 7, 0 == 'abc' was true; on PHP 8 it is false. A suite full of assertEquals on mixed-type data changes meaning the day you upgrade the runtime — a green build on 7.4 can be red on 8.1 for reasons that have nothing to do with your code. For money and identifiers, compare in integer cents and use assertSame, so the test fails on "1200" before your ledger does.

Arrays deserve the same discipline. assertSame on arrays demands identical types and order, which is correct for a sorted result the API promises. When the contract is membership rather than order — rows pulled from a database with no ORDER BY — assertEqualsCanonicalizing compares sorted copies and stops the suite from failing on a harmless reordering:

$this->assertEqualsCanonicalizing([1050, 1200], $totals);   // passes for [1200, 1050]
$this->assertSame([1050, 1200], $totals);                   // fails on the order

Objects force you to ask a second question: equal, or the same instance?

$a = new Money(1200);
$b = new Money(1200);

$this->assertEquals($a, $b);   // passes — same attributes, compared recursively
$this->assertSame($a, $b);     // fails — two distinct instances
$this->assertSame($a, $a);     // passes — reference identity

assertEquals walks both objects attribute by attribute; assertSame is ===, which for objects means identity. When a test must prove the collaborator received the very object the caller constructed, only assertSame can express it; when two DTOs are built independently from the same payload, only assertEquals will. The boolean helpers obey the same rule — assertTrue($flag) insists on a real boolean, while assertEquals(true, 'yes') passes, which is never what a flag check meant.

The failure output is the payoff. assertEquals prints a --- Expected / +++ Actual diff, which is unreadable when the only difference is a type; assertSame prints both values plus their types, so 1200 (integer) versus "1200" (string) is diagnosable from the CI log alone. That difference is why reviewers ask for assertSame on scalars, and it is the first thing interviewers probe in this area.

Value checks are half the job. The other half is proving the code refuses to go on.

A validation method that is supposed to throw has a way of never throwing — and the test stays green anyway.

public function testRejectsExpiredCoupon(): void
{
    try {
        $this->checkout->applyCoupon('EXPIRED-2024');
    } catch (ExpiredCouponException $e) {
        $this->assertSame('EXPIRED-2024', $e->couponCode());
    }
    // no exception thrown? the test still passes
}

This is the most common false-green in PHP testing: if the guard disappears, the catch block never runs, zero assertions execute, and CI reports success. Delete the catch and let the runner own the expectation instead:

public function testRejectsExpiredCoupon(): void
{
    $this->expectException(ExpiredCouponException::class);
    $this->expectExceptionMessage('EXPIRED-2024');

    $this->checkout->applyCoupon('EXPIRED-2024');
}

Three mechanics matter.

Order is load-bearing. expectException() must be called before the line that throws. It configures the runner's state for this test method; if you set it after, the exception escapes as an error with the same name but a different meaning (uncaught exception versus an expected outcome).

The message matcher is a substring match. expectExceptionMessage('EXPIRED-2024') passes when the message is Coupon EXPIRED-2024 is no longer valid, which is usually what you want — you are pinning the identifying detail, not the prose. When the shape matters, expectExceptionMessageMatches('/^Coupon [A-Z0-9-]+ expired on \d{4}-\d{2}-\d{2}$/') pins it with a regex. Assert on stable, identifying fragments; asserting the full sentence means a copy-editing pass breaks the build.

The class check is instanceof. A test expecting InvalidArgumentException passes if the code throws a subclass such as DomainException extends InvalidArgumentException. That is normally correct — substitutability is the point — but if you must pin the exact class, add $this->expectException(ExpiredCouponException::class) and assert the class name in a separate happy-path check of the exception object itself.

What expectException does not buy you: a test proving no exception occurs. That comes for free — if the happy path throws, the runner catches it and fails the test as an error. So you never write "expect nothing"; you just assert the returned value.

When a test legitimately has no assertions — a smoke test that only checks a class boots — say so with expectNotToPerformAssertions() or #[DoesNotPerformAssertions], otherwise it is flagged risky and, with the failOnRisky flag from Configuring PHPUnit, fails the build.

What expectException cannot do is worth stating plainly, because it tells you when to fall back to the explicit form: it asserts the type (and optionally the message) of one exception, and nothing about the exception's payload. When the values matter — the coupon code, the offending field, the expiry date — you need the object itself:

try {
    $this->checkout->applyCoupon('EXPIRED-2024');
    $this->fail('expected ExpiredCouponException, none thrown');
} catch (ExpiredCouponException $e) {
    $this->assertSame('2024-12-31', $e->expiredOn());
    $this->assertSame('EXPIRED-2024', $e->couponCode());
}

The fail() line is not optional — it is what makes the no-exception case red instead of silently green. Use this shape only for payload assertions; for "does it throw at all?", expectException() is shorter and impossible to get backwards.

And one expected exception per test. Two expectException() calls do not mean "either is acceptable": PHPUnit records a single expected exception per method, so assert the common parent type or your own marker interface, or split into two tests. When the wrong type shows up, the runner names it:

Failed asserting that exception of type "DomainException" is thrown.

Note the class check behaves like instanceof: expecting InvalidArgumentException passes when a subclass is thrown, because a subtype is a valid instance of the expected type.

Expectations tell the runner what should happen. Next: making the failure message tell you what actually did.

The test failed in CI. The log says Failed asserting that 119.99 matches expected 120.0. Which input, which rule, which feature? Sixty seconds later you are reproducing locally to answer a question the assertion could have answered itself.

Every assertion takes a custom message as its last argument, and it is printed first.

$this->assertSame(
    1200,
    $cart->totalWithTax(rate: 0.20),
    'total for a 1000-cent item at 20% tax must round to integer cents'
);

The message earns its place when the numbers are not self-explanatory — money, pagination offsets, retry counts, IDs generated by a contract you are not testing. Write it as the invariant, not a restatement: 'total must round to integer cents' beats 'total is wrong', because the reader can evaluate it against the code without opening anything.

Pick the assertion that produces the most useful failure. A short catalogue you will use constantly:

Each of these fails with an exact, domain-shaped message. assertTrue($total === 1200) fails with Failed asserting that false is true — the assertion threw away the two values you needed.

Reading diffs is a skill worth naming in an interview. assertEquals on arrays prints a unified diff, so a swapped pair shows as - 'b' / + 'a' at a specific offset; assertSame prints value and type, which is how you catch a string sneaking past a loose comparison. When the diff is long, the custom message is the one line that tells you which rule to read.

Watch the summary line in every run:

OK (14 tests, 41 assertions)

That count is not a score — it is a smell test. A test method that reaches the end with zero assertions is reported risky. Assertion counts also expose a lazy habit: calling assertNotNull() on a mocked collaborator to "add an assertion" when the real check was whether that collaborator was called at all. Interaction checks live later on this roadmap; the immediate consequence of precise assertions is that copying a test method for a twentieth input stops being attractive. Growing one check across many inputs without copy-paste is what Parameterized Tests with dataProvider solves.

Since the phase before this one built JSON APIs, three assertions will carry most of your integration work:

$this->assertJsonStringEqualsJsonString($expected, $response->getBody());
$this->assertStringContainsString('"status":"failed"', $body);
$this->assertContains('already-taken', $errors);      // strict: in_array with ===

assertContains is strict in exactly the way assertSame is strict — assertContains('1', [1, 2]) fails because the types differ, and assertContains(1, ['1']) fails for the same reason. assertStringContainsString is the substring form for bodies and messages, while assertStringEqualsFile() snapshots an entire fixture. Which one you pick decides how much of the payload the failure output can show you.

Here is the shape of a well-armed failure in a CI log:

1) OrderTest::testTotalIncludesTax
Failed asserting that 119.99 matches expected 120.0.

total for 3 items at 20% tax must round to integer cents

Both lines matter: the first gives you the numbers, the custom message gives you the rule that broke. Set that beside Failed asserting that false is true and the reason teams standardize on explicit assertions is obvious. One more runner detail: PHPUnit 10+ prints counts first and defers the rest, so --display-deprecations --display-warnings --display-incomplete --display-skipped are what surface the bodies of anything that did not fail outright.

Finally, name tests so the human-readable report reads like a spec: run vendor/bin/phpunit --testdox and the output becomes a checklist of guarantees (✔ Rejects an expired coupon) instead of a wall of method names. Reviewers read the checklist; missing behavior shows up as a missing line.