Change error message of a failing `assert_eq!`

I appreciate the ideas mentioned

• custom names for the sides
• capturing the expressions for the sides

I have an anecdote that can help add some flavor to this conversation. Not saying it means we have to go a particular direction.

I maintain a snapshotting library, snapbox. You can think of it as a mix of expect-test, assert_cmd, and assert_fs (I maintain the latter two also).

snapbox started with:

• assert_data_eq!(expected, actual)
• OutputAssert::stdout_eq(expected)
• Assert::eq(expected, actual)
• Assert::subset_eq(expected_root, actual_root (for asserting that expected_root directory has a subset of the files of actual_root and those files are eq)

Note: As a reminder, as a snapshotting library, the order is not just visual but also affects whether whether it can detect if it is given a snapshot, a source file that it is allowed to mutate when "blessing" the current output.

Because a failed assertion is shown as a diff, this was meant to mirror diff expected actual. There might have also been a grammatical aspect to Assert::subset_eq.

Despite the analog to diff expected actual, I was regularly confused by this. OutputAssert also doesn't align with this order.

A user also opened an issue about this at Snapbox parameter order (expected, actual) breaks common convention · Issue #226 · assert-rs/snapbox · GitHub. In that, I looked at some prior art

Then in talking over the above with @Muscraft that led to "why is there a preference for one over the other" and this got me looking at prior art

• rust only has (left, right)
• pretty_assertions maintains the concept of (left, right) and lines up with (expected, actual) for how we show the diff
  • same for similar-asserts
• insta inline snapshots do (actual, snapshot)

Since then, we've switched the order for non-directory assertions:

• assert_data_eq(actual, expected)
• OutputAssert::stdout_eq(expected)
• Assert::eq(actual, expected)
• Assert::subset_eq(expected_root, actual_root (I assume for grammar reasons? also not as commonly used)

Since that change, snapbox has replaced cargo's bespoke assertions. I've not had any confusion and I've not heard of any confusion.