• Context: Our JavaScript test assertion helpers generally treat the first argument as the expected value and the second as the actual value, for example assert.docEq(expectedDoc, actualDoc, ...) and assert.setEq(expectedSet, actualSet, ...).

• Issue: The implementation and documentation of assert.eq in src/mongo/shell/assert.js currently invert these roles: the JSDoc example uses assert.eq(actual, expected), while the failure message is formatted as expected `aDisplay` to equal `bDisplay`, leading to confusing labeling when most call sites pass arguments as (expected, actual).

• Additionally, patchDiff(a, b) renders a header "+ expected\n- actual" that does not clearly align with how the a and b parameters are used, further increasing ambiguity when reading diffs produced by failed assert.eq calls.

• Current usage: Across the test suite, assert.eq is mostly invoked with the first parameter as the expected value and the second as the actual value, e.g. assert.eq(expectedResult.options, result.options, ...), assert.eq(11.6, bitsValue, "Expected bits=11.6 ..."), and similar patterns in sharding/catalog tests and FCV upgrade tests.

• This mismatch between the long‑standing convention (expected, actual) and the newer assert.eq messaging makes debugging failed assertions harder, because the values labeled as “expected” and “actual” in logs do not consistently match how the test code is written.

Proposal

• Update assert.eq (and any equivalent helpers that generate comparison messages) so that:

• • The API and docs explicitly treat the first parameter as expected and the second as actual.

• • The failure message and diff header consistently label the first argument as expected and the second as actual.

• • The JSDoc example is updated to use assert.eq(expected, actual) to match the rest of the assertion helpers and typical test usage.

• Optionally, audit for any call sites that were written following the inverted (actual, expected) example and fix them for consistency.