skip to content

How do assertArrayEquals and assertIterableEquals compare their inputs, and how does that differ from calling assertEquals on a List or array?

level: middleimportance: should knowfreq 45%

answer

  1. arrays: no content equals() -> use assertArrayEquals
  2. assertEquals(array, array) compares references (fails)
  3. assertIterableEquals = pairwise in-order over any Iterable
  4. List/Set override equals() so assertEquals(list,list) works
  5. both are order-sensitive; sort or AssertJ for unordered

basics

~20 s

assertArrayEquals compares two arrays element by element (in order). assertIterableEquals walks two iterables (like Lists) and compares elements pairwise. assertEquals on raw arrays compares references, not contents, so it usually fails even when contents match.

solid answer

~40 s

For collections you need content comparison, not reference comparison. assertArrayEquals(expected, actual) iterates both arrays and checks each element is equal at the same index, with overloads for primitive arrays and a delta overload for double/float arrays. assertIterableEquals(expected, actual) does the same pairwise, in-order walk for any Iterable (List, Set, Queue), comparing elements with equals(). The trap is assertEquals: arrays don't override equals(), so assertEquals(arr1, arr2) compares array references and fails for two distinct-but-equal arrays — always use assertArrayEquals for arrays. For Lists, assertEquals works because List.equals() is content-and-order based, but assertIterableEquals is more flexible since it compares across different Iterable implementations (e.g. a LinkedList vs ArrayList) by element, not by the collection's own equals. For order-independent comparison neither fits; use assertEquals on sorted copies or an AssertJ containsExactlyInAnyOrder.

code

java · 20 lines
java
import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.Test;
import java.util.*;

class ArrayIterableAssertTest {
    @Test
    void arraysNeedAssertArrayEquals() {
        int[] a = {1, 2, 3};
        int[] b = {1, 2, 3};
        // assertEquals(a, b); // FAILS: compares array references
        assertArrayEquals(a, b); // passes: element-by-element
    }

    @Test
    void iterablesCompareAcrossTypes() {
        List<Integer> expected = List.of(1, 2, 3);
        Iterable<Integer> actual = new LinkedList<>(List.of(1, 2, 3));
        assertIterableEquals(expected, actual); // passes
    }
}

go deeper

for a junior

Use assertArrayEquals for arrays and know assertIterableEquals exists for collections like Lists.

for a middle

Explain that arrays lack a content equals() (so assertEquals compares references), that assertIterableEquals walks elements pairwise in order, and that List.equals is content-based.

for a senior

Cover the delta overload for double[] arrays, cross-implementation comparison via assertIterableEquals, and order-independence strategies (sort or AssertJ).

for a principal

Guide teams toward expressive collection assertions (AssertJ) for readable failures and consistent order/identity semantics across the test suite.

## The core problem: contents vs references When you compare two collections in a test you almost always mean 'do they hold the **same elements in the same order**', not 'are they the **same object**'. JUnit's general `assertEquals` delegates to the argument's `.equals()` method — and that behaves very differently for arrays versus `List`s. ## Arrays don't have a content equals() Java **arrays do not override `equals()`**. An array's `equals()` is just `Object.equals()`, i.e. reference identity (`==`). So: ```java int[] a = {1, 2, 3}; int[] b = {1, 2, 3}; assertEquals(a, b); // FAILS — different array objects, even though contents match ``` The right tool is **`assertArrayEquals`**: ```java assertArrayEquals(new int[]{1,2,3}, b); // passes — element-by-element, in order ``` `assertArrayEquals` has overloads for every primitive array type (`int[]`, `long[]`, `byte[]`, …) and for `Object[]`, plus a **delta** overload for `double[]`/`float[]` (same floating-point tolerance idea as scalar `assertEquals`). For nested arrays (`Object[]` containing arrays) it compares **deeply**. ## assertIterableEquals for Lists and other iterables **`assertIterableEquals(expected, actual)`** takes two `Iterable`s and walks them **in parallel**, comparing element *i* of one to element *i* of the other with `.equals()`. It passes when both have the same length and all paired elements are equal — order matters. ```java assertIterableEquals(List.of(1,2,3), new java.util.LinkedList<>(List.of(1,2,3))); // passes ``` Its advantage over `assertEquals` is that it does **not** rely on the collections being the *same type* or on the collection's own `equals()`. `ArrayList.equals(LinkedList)` happens to work because `List.equals` is defined across `List` implementations, but `assertIterableEquals` compares element-wise regardless of implementation and works for `Set`, `Queue`, or any custom `Iterable`. ## When assertEquals on a List is fine Unlike arrays, **`List` (and `Set`, `Map`) override `equals()`** with content semantics. So `assertEquals(List.of(1,2,3), actualList)` works correctly — `List.equals` checks size and ordered element equality. Use it freely for lists; reach for `assertIterableEquals` when comparing across different `Iterable` types or non-`List` iterables. ## Order independence — neither helps Both `assertArrayEquals` and `assertIterableEquals` are **order-sensitive**. If you only care that the same elements are present regardless of order, sort copies first and compare, or use a library: AssertJ's `assertThat(actual).containsExactlyInAnyOrder(...)`. ## Summary table - Two arrays, content+order → `assertArrayEquals` (never `assertEquals`). - Double/float arrays → `assertArrayEquals(..., delta)`. - Two iterables, content+order, possibly different types → `assertIterableEquals`. - Two `List`s of the same semantics → `assertEquals` is fine (List.equals is content-based). - Order-independent → sort-then-compare or AssertJ.

  • Why does assertEquals(new int[]{1,2,3}, new int[]{1,2,3}) fail?
    Arrays don't override equals(), so assertEquals uses reference identity. The two arrays are different objects, so it fails despite identical contents. Use assertArrayEquals, which compares element-by-element.
  • How would you assert two lists contain the same elements regardless of order?
    Neither assertIterableEquals nor assertArrayEquals helps since both are order-sensitive. Sort copies of both lists and assertEquals them, or use AssertJ's assertThat(actual).containsExactlyInAnyOrder(expected...).

saying these in an interview costs you the question

  • Using assertEquals to compare two arrays' contents
  • Believing assertIterableEquals ignores order
  • Not knowing arrays lack a content-based equals()

context

resolving links…