The class org.junit.jupiter.api.AssertionUtils and its methods should be public

[twwwt]

For our own purposes, we have implemented additional assertion methods (assert...(...)) in a test utility class. Motivated by reusing existing functionality, this class makes use of the static methods of org.junit.jupiter.api.AssertionUtils; mostly for throwing assertion errors and for formatting error messages. AssertionUtils and most of its methods, however, are package-protected. In order to make them visible to our class, we have put it in the same package org.junit.jupiter.api. Now that we are using Java's module system, we can no longer proceed this way since Java's module system does not allow to have the same package in more than one module. Therefore I would like to propose to make org.junit.jupiter.api.AssertionUtils public as well as all its methods that are currently package-protected.

Note that there are a couple of other utility classes in org.junit.platform.commons.util that are already public; though org.junit.jupiter.api.AssertionUtils is in junit-jupiter-api while org.junit.platform.commons.util is in junit-platform-commons. I'm not necessarily proposing to also relocate AssertionUtils into junit-platform-commons: But if that makes sense, it seems better. junit-platform-commons is already a compile dependency of junit-jupiter-api.

Deliverables

• Pull request?

[sormuras]

Having and keeping internal utility classes/methods concealed was a design decision made on purpose. I don't think that will "make org.junit.jupiter.api.AssertionUtils public as well as all its methods that are currently package-"private.

As you noted, module org.junit.platform.commons exports its package org.junit.platform.commons.support with the following comment:

/**
 * Maintained common support APIs provided by the JUnit Platform.
 *
 * <p>The purpose of this package is to provide {@code TestEngine} and
 * {@code Extension} authors convenient access to a subset of internal utility
 * methods to assist with their implementation. This prevents re-inventing the
 * wheel and ensures that common tasks are handled in third-party engines and
 * extensions with the same semantics as within the JUnit Platform itself.
 */

Perhaps something like this might be doable for Jupiter's low-level assertion utilities as well? 🤔

[marcphilipp]

Motivated by reusing existing functionality, this class makes use of the static methods of org.junit.jupiter.api.AssertionUtils; mostly for throwing assertion errors and for formatting error messages.

Which of them are you using?

[twwwt]

Which of them are you using?

org.junit.jupiter.api.AssertionUtils.buildPrefix(String message)
org.junit.jupiter.api.AssertionUtils.fail(String message)
org.junit.jupiter.api.AssertionUtils.failNotEqual(Object expected, Object actual, String message)

failNotEqual has a rather large call tree.

[jbee]

👍

There is some logic in how values are formatted and printed which is inaccessible when building own assertions. To have the same logic applied it would be good to have some way to use these methods. But this could be done in a different way than exposing the utils. For example by exposing another method or exception that later is passing things through these utils.

[marcphilipp]

Team Decision: Explore adding an API to make failure message formatting publicly accessible.

[marcphilipp]

@twwwt @jbee Please see the API proposal in #2972. Feedback appreciated!

[twwwt]

@marcphilipp Looks good to me.

Thanks for quickly adding this new class, and for integrating it already in the upcoming release!

[marcphilipp]

@twwwt Thanks for the feedback!

Reopening the issue since the corresponding PR is not yet merged.