Custom Asserts – what and why

Articles Oct 31, 2025 (Oct 31, 2025) Loading...

Terminology

Gerard Meszaros’ comprehensive 2006 xUnit Patterns book uses the term custom asserts, Chai’s docs pull them into the collective term helpers, Hamcrest calls them matchers, and I’ve often called them custom matchers. Here, we’ll use Meszaros’ term – it’s oldest, and the description is the deepest.

In automated tests, keywords likeassertorexpect or should wrap round a comparison between some expectation, and some measurement taken during the test. There are typically asserts like toBeEqualTo and toBe, with decorations like not.toBe and complications like toContain.

A custom assert is written for the system under test, and usually wraps around one or more of these simple checks. It’s an abstraction to help the tests be understood by humans. It needs an understandable name, and a place to live.

Handy Things

A custom assert is useful because:

it can give better messages
it gives a name to more-complex checks and abstracts them to a single thing
it can be reused in several tests, across different teams
it can be reused outside unit tests (sometimes)
tests using well-named custom asserts are shorter and more descriptive – and so their intent may be more obvious
using shared custom asserts allows updates in one place to be used in several, making the tests easier to evolve as the system evolves
when checks fail because of a change to a shared custom assert (and they will, which can hurt), that failing can expose misunderstandings between teams, and can expose problems with the test architecture.
they can be tested independently of the system-under-test, so can be tuned or made more reliable

Engineering?

If your test automation is littered with copy-pasted bitrot, Custom asserts are one gateway to ‘engineered’ test code because they require some engineering up-front to let testers 1) build code 2) share code 3) put their shared code into change control 4) plug into whatever enables reuse in their team. The results and potential of that engineering can be seen swiftly across a team, letting you make a small experiment into an achievable and costed improvement.

For funsies, set up a single file that can be accessed by tests running on anyone's machine. If you can't do that, take a moment and think of how handy that might be. Doesn't have to be live, can be a local repo. Stuff a custom matcher in it for something that you already use in more than one place. Refactor a test or three to use it. Show a colleague. Use it on their machine. Keep going if it seems useful.

Some of you may smirk. Good for you. Some poor sod is starting today, as an SDET in a company whose name you know, and finds that plenty of tests have all the steps, but no checks that any values are right. The barest of happy-path confirmatory validation (vom-firmatory?) relies on the system failing obviously, and nothing as subtle as checking that something has a value that can be predicted.

Making custom asserts

Custom asserts are typically simple, encapsulated, and have really good examples – making them good candidates for generation via LLMs. We need to build them, rather than use libraries, because they typically express something specific about the system we’re testing – but they seem to be a pain to get right because they’re also different across different unit test platforms.

An LLM assist can get you off the blocks.

Here are some exercises to get you started.