Assertion libraries

Assertion libraries

An assertion is where a test states what it expects, and its output is the first thing you read when it fails. A bare assert result prints "false" and tells you nothing; a good assertion prints the expected value, the actual value, and enough of the surrounding structure to locate the divergence. The library and style you choose largely decide which of those two failures you get.

Method

1. Prefer expressive matchers over boolean asserts. Reach for an assertion that captures both sides: assertThat(actual).isEqualTo(expected), expect(x).toEqual(y), result.should.equal(...). On failure these print a structured diff; a hand-rolled assert a == b prints only the line, not the values.
2. Assert the specific property, not a coarse truth. expect(list) .toContain(x) and assertThat(user.name).isEqualTo("Ada") fail with a precise message. assert x in list reduced to a boolean throws away the values, so wrap the value, not the comparison result.
3. Use deep and structural matchers for objects and collections. Compare whole structures with toEqual or isEqualTo deep equality and pick out fields with matchers (objectContaining, hasItem, AssertJ extracting) so the failure shows which field of which element differs, not just "objects not equal".
4. Keep one logical assertion per test, or group them. A test that checks six unrelated things stops at the first failure and hides the rest. Split them, or use a soft-assertion block (SoftAssertions, expect.soft) that reports every failure in one run when the checks genuinely belong together.
5. Write custom matchers for domain concepts. When you repeatedly assert the same shape, define a matcher (toBeValidOrder, a Hamcrest TypeSafeMatcher) so the test reads in domain terms and the failure message speaks that language instead of dumping raw fields every time.
6. Assert on errors by type and message, not just that something threw. Use assertRaises(ValueError, match="negative amount") or expect(fn).toThrow(/negative/) so a test cannot pass on the wrong exception. Catching bare Exception hides the case where the code failed for an unrelated reason.

Litmus tests

• From a failure message alone, without opening the test, can you tell what value was wrong?
• Does an equality failure on an object show a field-level diff, not "not equal"?
• Does an error assertion pin the exception type and message, so a different failure would not pass it?

Boundaries

This is about assertion style and readable failures, not what to assert, which is a design question the test's purpose answers. Snapshot assertions are a distinct trade-off with their own failure mode. Stay with the assertion library a project has adopted rather than mixing three dialects in one suite.