.toBe or .toEqual? That is the question

Testing with Jest: What to Use and Why

Matchers like .toBe and .toEqual are confusing because while they seem similar, they operate quite differently. When a test fails, we want it to fail because something in our code is wrong. It is both frustrating and unproductive to have a test fail because our test is wrong. With a good understanding of Jest matchers, we can write tests that behave exactly as we want them to behave and have confidence that the issue lies within our code and not the test itself.

Before diving into the intricacies of Jest matchers, it is best to quickly review JavaScript value vs. reference. JS variables can hold one of two types of data-primitive or reference. Primitive types, such as numbers, are passed by value. Take the following example:

And if we were to assign a variable to another variable:

If we were to compare them:

However, aside from holding the same value, a and b are ultimately unrelated to each other. All we have done is assign the value of a to the value of b. If we were to reassign a:

We will see that only the value of a has changed.

Simple enough. Yet, this does not hold true for a reference type. For example:

The objects are exactly the same, right? And yet…

This is because when comparing reference types, JS looks to the address in memory. So while c and d appear to be holding the exact same values they are not the exact same object. This hold true even when comparing two empty objects:

or two objects not assigned to variables:

or comparing an object with its apparent “value”:

When assigning a variable to another variable with reference types, it works differently than with primitive types:

We seem to have copied the value of c to d. However, when we want to update a property of d:

Yes, have updated d successfully. But there is a catch:

We have updated c as well! This is because-unlike with primitive types-we have not simply copied the value of c to the value of d. We have assigned the reference of c to the reference of d. They are now the exact same object in memory. Now:

This is why when we truly want to copy only an object’s values we must find another way, like using the spread operator:

Now we can update a property on d without affecting c:

Okay, still with me? This may have seemed tedious, but understanding this fundamental JS principle is key in understanding Jest matchers. Now, let’s get to the point….

In other words, you are probably safe to use .toBe when working with primitive types. For reference types, it should be specifically used to check for the exact same object in memory. For example, if we are testing that a function mutates an object directly. Similarly, .toBe’s counterpart-.not.toBe-is helpful for ensuring object mutation is avoided.

In simpler words, .toEqual does not look at reference. For primitive types, it works much the same as. toBe and compares value:

The biggest difference is its behavior with objects. .toEqual looks at key value pairs and tests for equality, rather than making sure they are truly the same object (same reference in memory).

And that’s about it! Of course, there are more subtle nuances between these two and I would suggest going through the docs to dive deeper into those. Jest also has a plethora of other matchers for edge cases and testing objects in different ways (.toMatchObject, .toContain, .toHaveProperty, etc). Hopefully though, this clears up any confusion about the basics of .toBe and .toEqual, as well as JS value vs. reference.

Related posts:

We know that parents and guardians play a critical role in the education of their children. At CommonLit, we have developed our reading program to be user-friendly and to support students with…

I really wanted to tell you all my progress with my email marketing tricks, and how I got more than 3,000 clicks with the sending of an email and an opening percentage of over 58%. Well, maybe you…

I recently applied for the Symfony Certification and I thought: If I read all the documentation, I’m good to go, right? The Symfony documentation is great! But to be sure I read everything I wanted…