Why is there no Assertions.assertEquals(boolean, boolean) method?

[Thilo-Acrolinx]

If my counting is correct, then there are currently 93 overloaded "assertEquals" methods in the org.junit.jupiter.api.Assertions class (link to Javadoc). Despite this impressive API, there seems to be no simple assertEquals(boolean, boolean) method to compare two primitive boolean values in JUnit 5.

I am aware of the assertTrue(boolean) and assertFalse(boolean) methods. However, these methods imply that at the time of writing a test I already know whether or not a primitive boolean value should be true or false. This may often be the case, but not always. Every now and then it happens that I get two primitive boolean values programmatically at runtime and I want to make sure they are equal (= either both true or both false).

Of course I can write my own little helper method and use some if-else as work-around: value1 ? assertTrue(value2) : assertFalse(value2). But this is ugly and adds unnecessary complexity on each code base where there is such a need.

Another work-around is to use the assertEquals(Object, Object) method and rely on auto-boxing from primitive boolean values to Boolean objects. While this technically works, I would argue that this is also ugly and (depending on the configuration) may result in warnings from the compiler and/or static code analysis tools.

I understand that API design is hard and that it is sometimes not possible to support all use-cases, somewhere a line has to be drawn. But given there are already 93 assertEquals() methods, including for all other primitive types (byte, char, float, double, int, short, long), the lack of a simple assertEquals(boolean, boolean) method looks to me like a gap and inconsistency in the API. It should be easy to fix this without adding a lot of complexity or breaking the backwards compatibility of JUnit, so I wonder if there are any reasons why this has not already been done long ago?

[mpkorstanje]

I wonder if there are any reasons why this has not already been done long ago?

The Assertions API is designed to test expectations. This implies knowing what the expected value will be. So in case of a boolean, either true or false.

Though you could accurately express the expectation that both services return then same boolean value by using assertTrue(a == b).

Note: Not part of the JUnit team. And this API originally comes from JUnit 4, so finding the motivation of the original authors for using assertTrue/False instead of assertEquals(a, true) would be hard.

[Thilo-Acrolinx]

Using assertTrue(a == b) is possible, but in my opinion just another bad workaround. If the assertion fails, you only get an "Expected true but was false" error message which does not include the values of the two boolean variables.

Hopefully nobody writes assertTrue(42 == 43) but assertEquals(42, 43) instead. The later results in a nice "Expected 42 but was 43" error message.

I could create a PR to add another overloaded Assertions.assertEquals(boolean, boolean) method, if everybody is happy with this?

[mpkorstanje]

Using assertTrue(a == b) is possible, but in my opinion just another bad workaround. If the assertion fails, you only get an "Expected true but was false" error message which does not include the values of the two boolean variables.

As we are starting from a situation where you don't know which service provided the expected and which service provides the actual value are that would be equally misleading.

You could use assertTrue(a == b, () -> "service a (%s) and b (%s) do not agree".formatted(a, b))) and that would be more accurate

But also more code. Though that code would be used to solve a problem outside of the purpose of the assertions API, so not actually a bad thing.

I could create a PR to add another overloaded Assertions.assertEquals(boolean, boolean) method, if everybody is happy with this?

I'm not part of the JUnit Team so I can't give you a definite answer either way.

But I do think your use case falls just outside the purpose of the assertions API. The assertions API expects that you test an expected (constant) value against an actual value from a test. So I don't think your proposal would have much success.

Edit: Should you want to make a proposal anyway, I think you'd have to make it clear that one of the services provides the expected value, explain why it can change and that this is a common situation, and how the solution solves a general problem.

[sbrannen]

Despite this impressive API, there seems to be no simple assertEquals(boolean, boolean) method to compare two primitive boolean values in JUnit 5.

There's no concrete need for such an assertion method.

Primitive boolean values will be automatically boxed into Boolean wrappers.

For example, the following test ...

@Test
void assertBooleansAreEqual() {
	boolean a = true;
	boolean b = false;
	assertEquals(a, b);
}

... fails with:

org.opentest4j.AssertionFailedError: expected: <true> but was: <false>

And that's by design.

In light of that, I'm closing this discussion.

[Thilo-Acrolinx]

I tried to explain in my original question why autoboxing boolean primitives into Boolean wrappers is not always a good idea in my opinion. You also did not answer why we have overloaded assertEquals() methods for all other seven primitives. If we follow your logic, then these methods could all be removed in favor of assertEquals(Object, Object). Should not a good API be consistent and unambiguous?

[sbrannen]

I tried to explain in my original question why autoboxing boolean primitives into Boolean wrappers is not always a good idea in my opinion.

As I mentioned previously, we've never had a "concrete reason" to introduce assertEquals(boolean, boolean) or assertNotEquals(boolean, boolean), simply because we have assertTrue(boolean), assertFalse(boolean), assertEquals(Object, Object), and assertNotEquals(Object, Object).

In other words, the auto-boxing from boolean to Boolean has never been raised as an issue until now.

If that is truly problematic for you, please open an issue to request new assertion methods; however, please read the following first.

You also did not answer why we have overloaded assertEquals() methods for all other seven primitives.

We have those in order to support combinations of primitives and their wrappers and to ensure that compilers know which method to choose.

Related Commits/Issues

• c8a49a0
• 0ec5a7b
• 382e9ea

If we follow your logic, then these methods could all be removed in favor of assertEquals(Object, Object).

No. See the linked issues above.

In addition, as @mpkorstanje pointed out, I originally copied (almost) all assertions from JUnit 4 when we introduced the Assertions class in JUnit Jupiter. The rationale for that was to provide an API familiar to existing JUnit users (and easier to migrate to).

And please note that org.junit.Assert does not declare an assertEquals(boolean, boolean) method.

Should not a good API be consistent and unambiguous?

Yes, of course.

But... by my calculations we would need 12 new assertEquals() methods and 12 new assertNotEquals() methods in order to properly support boolean primitives and their wrappers.

I'm not saying we couldn't do that. Rather, I'm just saying I'm not sure if it's warranted.

In any case, like I said above, if you feel strongly about this, feel to create an issue, and we'll discuss it within the team.

Cheers,

Sam