Why are assertEquals() parameters in the order (expected, actual)?

Because the authors had a 50% chance of matching your intuition.

Because of the other overload

assertWhatever(explanation, expected, actual)

And the explanation, which is part of what you know, goes with the expected, which is what you know, as opposed to the actual, which you don't know at the time you write the code.

The answer from Kent Beck, co-creator of JUnit (where possibly this convention originates, since his earlier SUnit doesn't appear to have included assertEquals):

Line a bunch of assertEquals in a row. Having expected first makes them read better.

In the initial version of my answer, I said that I didn't understand this. Here's what I often see in tests:

assertEquals(12345, user.getId());assertEquals("kent", user.getUsername());assertEquals("Kent Beck", user.getName());

I would think this would read better with the actual value first. That puts more of the repetitive boilerplate together, aligning the method calls whose values we're testing:

assertEquals(user.getId(), 12345);assertEquals(user.getUsername(), "kent");assertEquals(user.getName(), "Kent Beck");

(And there are other reasons that I prefer this order, but for the purpose of this question about why it's the other way, Kent's reasoning appears to be the answer.)

However, Bob Stein has a comment below (much like this one) that suggests a couple things that "expected first" has going for it. The main idea is that expected values are probably typically shorter -- often literals or variables/fields, rather than possibly complex method calls. As a result:

• It's easier to identify both the expected and actual values at a glance.
• It's possible to use a small amount of extra whitespace to align them (if you prefer that kind of thing, though I don't see it used in the earliest JUnit commit I could find easily):

assertEquals(12345,       user.getId());assertEquals("kent",      user.getUsername());assertEquals("Kent Beck", user.getName());

Thanks, Bob!

An ulterior purpose of assertEqual() is to demo code for human readers.

A simple function call shows the return value on the left and the call on the right.

    y = f(x)

Following that convention, a self-testing demonstration of the function could look like:

    assertEqual(y, f(x))

The order is (expected, actual).

Here's a demo of the sum() function with a literal expected return value on the left, and a function call that calculates the actual return value on the right:

    assertEqual(15, sum((1,2,3,4,5)))

Similarly, here's a demo of an expression. It is also natural in (expected, actual) order:

    assertEqual(4, 2 + 2)

Another reason is stylistic. If you like lining things up, the expected parameter is better on the left because it tends to be shorter:

assertEqual(42, 2 * 3 * 7)assertEqual(42, (1 << 1) + (1 << 3) + (1 << 5))assertEqual(42, int('110', int('110', 2)))

I suspect this solves the mystery @ChrisPovirk raised about what Kent Beck meant by "expected first makes them read better."

_{Thanks Andrew Weimholt and Ganesh Parameswaran for these formulae.}