assertEquals() vs. assertSame() in JUnit

1. Overview

JUnit is a popular testing framework. As a part of its API, it provides a convenient way to check and compare objects. However, the difference between the two methods, assertEquals() and assertSame(), isn’t always obvious.

In this tutorial, we’ll check the assertEquals() and assertSame() methods. They’re present in both JUnit4 and JUnit5 and behave the same way. However, in this article, we’ll use JUnit5 in the examples.

2. Identity and Equality

When we compare two objects, we use two concepts: identity and equality. Identity checks if two objects or elements are identical. For example, two people cannot be considered identical in the physical sense. In computer science, it’s easier as we work with the concepts of references.

The sun people see in any part of the world is identical. Any image of the sun in a movie or a picture is the same sun we can see through our windows. Thus, we have different representations of a single underlying object.

At the same time, equality doesn’t necessarily consider object identity but checks if they can be regarded as equal. It is a more flexible concept that can be represented differently depending on the context. For example, people cannot be considered identical (in the physical sense) but can be equal in different aspects: height, age, occupation, etc.

Two identical objects are equal by default, but two equal objects aren’t necessarily identical.

3. equals() and ==

In Java, the concepts of identity and equality can be represented with the == and the equals() method. We can see their behavior with Strings:

@ParameterizedTest
@ValueSource(strings = {"Hello", "World"})
void givenAString_WhenCompareInJava_ThenItEqualsAndSame(String string) {
    assertTrue(string.equals(string));
    assertTrue(string == string);
}

This shows that if we have the same object, it would be both identical and equal to itself. However, if we have different instances with the same content, we’ll have a different picture:

@ParameterizedTest
@ValueSource(strings = {"Hello", "World"})
void givenAStrings_WhenCompareNewStringsInJava_ThenItEqualsButNotSame(String string) {
    assertTrue(new String(string).equals(new String(string)));
    assertFalse(new String(string) == new String(string));
}

Here, the objects are equal but not identical. Sometimes, we might have issues with classes when we don’t provide an implementation for the equals() and hashCode() methods:

public class Person {
    private final String firstName;
    private final String lastName;
    // constructors, getters, and setters
}

Even with the same values, two instances won’t be identical, which is reasonable based on the explanation above. However, they also won’t be equal:

@Test
void givePeople_WhenCompareWithoutOverridingEquals_TheyNotEqual() {
    Person firstPerson = new Person("John", "Doe");
    Person secondPerson = new Person("John", "Doe");
    assertNotEquals(firstPerson, secondPerson);
}

This is because we’ll use the implementation of the equals() method from the Object class:

public boolean equals(Object obj) {
    return (this == obj);
}

As we can see, the default behavior falls back into identity comparison and checks the references instead of the objects’ contents. That’s why it’s important to provide a valid implementation of the equals() and hashCode() methods.

4. JUnit

After getting familiar with the concepts of identity and equality, it’s easier to understand the behavior of the assertEquals() and assertSame() methods. The first one is using equals() method to compare the elements:

@ParameterizedTest
@ValueSource(strings = {"Hello", "World"})
void givenAString_WhenCompare_ThenItEqualsAndSame(String string) {
    assertEquals(string, string);
    assertSame(string, string);
}

At the same time, the second one uses identity and checks both objects point to the same location in the heap:

@ParameterizedTest
@ValueSource(strings = {"Hello", "World"})
void givenAStrings_WhenCompareNewStrings_ThenItEqualsButNotSame(String string) {
    assertEquals(new String(string), new String(string));
    assertNotSame(new String(string), new String(string));
}

5. Conclusion

Identity and equality are related concepts but differ significantly in what they consider during comparison. Understanding these concepts can help us avoid subtle bugs and write more robust code.

As usual, all the code from this article is available over on GitHub.