Document when arrays are compared by their contents vs. their object identity

[kuanyingchou]

Hi, I got some strange results when comparing List of Arrays. It seems to work for Array of Arrays, List of Lists, and Array of Lists though:

        assertThat(emptyList<Any>()).isEqualTo(emptyList<Any>()) // true
        assertThat(emptyArray<Any>()).isEqualTo(emptyArray<Any>()) // true
        assertThat(listOf(1, 2, 3)).isEqualTo(listOf(1, 2, 3)) // true
        assertThat(arrayOf(1, 2, 3)).isEqualTo(arrayOf(1, 2, 3)) // true
        assertThat(listOf(listOf(1, 2, 3))).isEqualTo(listOf(listOf(1, 2, 3))) // true
        assertThat(listOf(listOf(1, 2, 3))).containsExactlyElementsIn(listOf(listOf(1, 2, 3))).inOrder() // true
        assertThat(arrayOf(arrayOf(1, 2, 3))).isEqualTo(arrayOf(arrayOf(1, 2, 3))) // true
        assertThat(arrayOf(listOf(1, 2, 3))).isEqualTo(arrayOf(listOf(1, 2, 3))) // true
        
        assertThat(listOf(arrayOf(1, 2, 3))).isEqualTo(listOf(arrayOf(1, 2, 3))) // false
        assertThat(listOf(arrayOf(1, 2, 3))).containsExactlyElementsIn(listOf(arrayOf(1, 2, 3))).inOrder() // false

This happens in version 1.1.3.

[cpovirk]

Our handling of arrays is confusing.

The main thing to know is that we normally compare objects for equality with Object.equals. And two different arrays with the same contents never compare as equal. By that logic, it's not surprising that a list of arrays will never be equal to another list of arrays (unless both lists contain the same array instances, not just the same contents).

The surprising thing is that, when you use assertThat(foo).isEqualTo(bar), if foo and bar are arrays, then we do compare their contents. That's why the examples in which the array is the "top-level" object work.

We could document this better.

If you do want to compare lists of arrays, then you'll need to tell Truth how to compare the arrays -- probably using Arrays.equals. You can do that by using Fuzzy Truth -- assertThat(listOfArrays).comparingElementsUsing(...).....

[cpovirk]

(Someone reminded me that the docs for this are better than I'd thought. There's still more we could say, but for some reason, I was thinking that we didn't yet say anything about this.)

[kuanyingchou]

Got it. Thanks for the explanations! Please feel free to close this one.