JSSmallTips — Creating custom matcher assertions with Jest
If you have been working with Javascript for a while, you’ve probably worked or at least seen something about automated tests using a lib called Jest. Currently, Jest is the most used and recommended library for dealing with unit and integration tests in Javascipt applications. I think one of the reasons for this is because it comes with a lot of things you can use to create good and reliable automated tests. One “thing” you will definitely be using all the time, while coding your tests, is matcher assertion.
Matcher assertions are methods we use in our tests to validate values and verify whether they meet certain conditions. There are a number of built-in matcher assertions provided by Jest.
But, even though it seems that Jest has all types of matchers you might need, it is possible that you find a specific scenario where this isn’t the case. So, wouldn’t be really handy for you, and your team, if there were a matcher that fits exactly that scenario and it’s also easy to use? That’s when custom matcher assertions comes in. Since creating all possible matchers we need would be an almost impossible task, the Jest community has provided a way for us to create our own matchers to suit our needs.
Let’s see how that works and what are the bennefits of creating our own matchers.
Creating our first custom matcher
Here is how a custom matcher looks like. Don’t worry, I’ll explain
To create a custom matcher we need to use the expect.extend function which takes an object as an argumment.
That object must have a function, which is your matcher. The function itself must return an object with 2 keys:
- pass: boolean — indicates whether there was a match or not (true or false)
- message: function — is a function that will returns an error message in case of failure.
Note: since we have cases where we need to assert whether THERE IS A MATCH or THERE IS NOT A MATCH. We need to provide a message for each
Talk is cheap, show me the code
Well, now that we know the theory, let’s create a custom matcher and see what we can do with it.
Let’s say we have functions that manipulate arrays of objects (removing, filtering or adding objects). We wanna make sure that our functions are doing what they are supposed to do and returning new arrays with or without certain objects.
To do so, we can use some built-in functions — equals, arrayContaining and objectContaining — that already exists in Jest and combine them to create a more straight forward and easy to use custom matcher. Given any key/value pair we pass as an argument to the matcher, it should tell us weather there is an object inside that array that matches the argument or not.
So, lets do that
Now, the usage
Scenario: We have a fellowship with some members and we wanna make sure that our functions, addMember and removeMember, are working fine.
To use our custom matcher the only thing we need to do is importing our jestCustomMatchers file with the custom matcher we just created
Result
Our tests passed!
To make sure it is everything alright, let’s force an error
Well, apparently our matcher is working just as expected.
So, that’s how we create our own matcher using Jest. Now it’s your time. Take a look into your application’s tests, maybe there is something you are doing repeatedly that you could improve by using this trick. Make your tests more readable and easy to use for you and your team. Explore all the possibilities provided by Jest. Btw.. you can create custom matchers that return a Promise of an object for async code, check that out!
Thanks for join me,
Cheers!
