What is the difference between 'toBe' and 'toEqual' in Jest?

Question

Jest documentation reads:

toBe just checks that a value is what you expect. It uses === to check strict equality.

And for toEqual:

Use .toEqual when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, toEqual and toBe behave differently in this test suite, so all the tests pass.

const x = { a: { b: 3 } };
const y = { a: { b: 3 } };

expect(x).toEqual(y);
expect(x).toBe(y);

In this case, toEqual passes but toBe fails. I understand that toEqual passes because it does a deep equal check. Why is toBe failing in this case?

Also, are there best practices for using toBe and toEqual (not just in Jest but in other testing frameworks, too)?

FYI: The documentation about the two methods are very common nowadays: - https://jestjs.io/docs/en/expect#toequalvalue - https://jestjs.io/docs/en/expect#tobevalue And both methods use `Object.is` internally. — karfau, Jan 17 '21 at 19:22

score 79 · Accepted Answer · edited Apr 11 '20 at 20:39

79

It fails cause x and y are different instances and not equal as in (x === y) === false. You can use toBe for primitives like strings, numbers or booleans for everything else use toEqual. For example

x = 4 
y = 4
x === y // true

x = 'someString'
y = 'someString'
x === y // true

Even empty objects are not equal

x = {}
y = {}
x === y //false

edited Apr 11 '20 at 20:39

CTS_AE

7,990
6
43
51

answered Jul 20 '17 at 08:38

Andreas Köberle

88,409
51
246
277

So I guess for non-primitives, `toBe` checks the memory address of the variable? – sshh Jul 20 '17 at 13:51
Its just a simple JS feature that you can compare primitives using `===` – Andreas Köberle Jul 20 '17 at 13:59
3

Is there any reason to use `toBe`? – Oliver Shaw Nov 24 '17 at 11:13
105

`toBe` or not `toBe`, that is the question. – Thomas Champion May 01 '18 at 13:57
64

@ThomasChampion Don't Jest... `toBe()` || `not.toBe()`, that is the test. – lonix Jan 30 '19 at 15:58
5

theQuestion = toBe || !toBe; – Coco Apr 02 '19 at 15:15
Really useful explanation! – Vladyn Jun 16 '19 at 18:37
10

@OliverShaw `toBe` or `toEqual` can be used with primitives, but `toBe` is specifically useful for reference equality aka. when you want to assert that it is literally the same instance of an object. – bingles Dec 11 '19 at 16:32
1

So basically `toBe` compares referential equality and `toEqual` compares deep properties? This answer is pretty poorly written. On one hand you say that we should use `toEqual` for objects as in `expect({}).toEqual({}) === true`, but in next sentence you say that _"empty objects are not equal"_. – Qwerty Mar 11 '21 at 05:27

score 12 · Answer 2 · answered Jun 20 '20 at 15:11

Suppose there are two players with same name and both of them scored 20.

let player1 = {
    name: "Amit",
    score: 20,
}

let player2 = {
    name: "Amit",
    score: 20,
}

Now I have a function which gives me 1st player.

function getFirstPlayer(player1,player2){
    return player1;
}

How will I test this function?

# 1st way
expect(getFirstPlayer(player1,player2)).toBe(player1); // Passes
expect(getFirstPlayer(player1,player2)).not.toBe(player2); // Passes

# 2nd way
expect(getFirstPlayer(player1,player2)).toEqual(player1); // Pases
expect(getFirstPlayer(player1,player2)).not.toEqual(player2); // Fails

toBe tests Identity and toEqual tests features. So twin kids can have same features but their real identity is different from each other. The way this function is designed we should use toBe.

Now I have a another function which increases the player score.

function addScore(player,scoreToAdd){
    player.score += scoreToAdd;
}

How will I test this function?

# 1st way
addScore(player1,20);
expect(player1).toBe({name:"Amit", score:40});  // Fails

# 2nd way
addScore(player1,20);
expect(player1).toEqual({name:"Amit", score:40});  // Passes

Did you notice that in 1st way we are passing a new player like entity in right hand side. Is there any chance that player1 has the same identity of newly created entity? Nope. So toBe will always fail in this case.

2nd way passes as in toEqual we are comparing features. Here player1 and newly created entity has same features.

Note: In context of javascript, primitive values like "Amit" is identity in itself. So

expect("Amit").toBe("Amit") // Passes

I have written this answer for particular case, when you get this idea of identity and features, you can implement it in your scenario.

score 6 · Answer 3 · edited Apr 11 '20 at 20:39

You have also toStrictEqual() since Jest v23

Explanations: https://jestjs.io/docs/en/expect#tostrictequalvalue

There is an ESLint plugin for Jest with a rule to enforce toStrictEqual(): https://github.com/jest-community/eslint-plugin-jest/blob/master/docs/rules/prefer-strict-equal.md

npm install --save-dev eslint-plugin-jest

// .eslintrc.js
module.exports = {
  extends: [
    'plugin:jest/recommended'
  ],

  rules: {
    'jest/prefer-strict-equal': 'error'
  }
}

score 1 · Answer 4 · answered Jul 20 '20 at 20:05

There's a few people saying that .toBe() is the same as x === y, but it's actually slightly different. Jest uses Object.is(x, y) when doing expect(x).toBe(y).

Unless you are verifying if a value is the same as a reference (like when checking if something got deepcloned properly), you should always use .toEqual(). And even in the deepclone example, I think it is cleaner to just do expect(x === y).toEqual(true) just to remove any confusion as to what you are trying to do.

You should not expect others to know the differences between toBe and toEqual, or to even know that Object.is exists and how it differs from ===. To avoid communication problems and testing issues, always use .toEqual, never use .toBe.

What is the difference between 'toBe' and 'toEqual' in Jest?

4 Answers4