Introduce new array assertions #6423
Description
Related to #6088.
There is a bit of frustration when it comes to comparing arrays in PHPUnit with assertEquals(), assertEquals(canonicalizing:true) and assertSame().
If we step back, what we may want to check with arrays is:
- the values are equal or strictly equal
- the keys matter
- the order of the keys matter
From this we can derive the following permutations:
| desired comparison | proposed API (1) | proposed API (2) | existing API |
|---|---|---|---|
| ordered strict comparison with keys (keys + order matter) | assertArraysIdentical | assertOrderedHashMapIdentical | assertSame |
| ordered loose comparison with keys (keys + order matter) | assertArraysEqual | assertOrderedHashMapEqual | |
| unordered strict comparison with keys (keys + order doesn't matter) | assertArraysIdenticalUnordered | assertUnorderedHashMapIdentical | |
| unordered loose comparison with keys (keys + order doesn't matter) | assertArraysEqualUnordered | assertUnorderedHashMapEqual | assertEquals |
| ordered strict comparison without keys (order matter) | assertArraysIdenticalValues | assertListIdentical | |
| ordered loose comparison without keys (order matter) | assertArraysEqualValues | assertListEqual | |
| unordered strict comparison without keys (order doesn't matter) | assertArraysIdenticalUnorderedValues | assertSetIdentical | |
| unordered loose comparison without keys (order doesn't matter) | assertArraysEqualUnorderedValues | assertSetEqual | assertEquals(canonicalizing: true) |
Rationale:
- I choose
IdenticalandEqualfor respectively the strict equality===and loose equality==as I think it matches the current PHPUnit naming convention. - I assumed ordered by default, just because when we do
assertSame(), we assume "exactly the same" and the order is part of that. However, we could also make it more explicit and add anOrderedsuffix.
Note that I proposed two APIs. I think the API 1 is the most natural and PHP like, as in, it's likely the expectation of a PHP developer that never really worked with proper data structures from other languages.
API 2 is another take where we convey whether the order or keys matters by using the "proper" corresponding data structure name. I provided it for completeness, but I don't think it would be a good idea for the following reasons:
- There is no universally agreed term for those data structures. Each language has their own although some uses the same term. E.g.
HashMapis used in Java and Rust but Python will useDictionaryand Go & JavaScript aMap. - Some of this API may lead to confusion:
assertListEquals()for instance already exists (so BC can be an issue), and it may have different expectations. Do you want to assert that the objects are equal when compared as lists, or do you want to assert that and that they are actual lists? - To both points above, we do have proper data structures as well in PHP via an extension, so the naming should maybe take after those instead: https://www.php.net/manual/en/book.ds.php.