AssertJ 4

[scordio]

Let's define the scope of the next major version:

• Move to Java 17 #3442
• Drop multi-release build in favor of module-only #3446
• Delete all deprecated elements
• Internal error message refactoring
• use the new recursive comparison API for iterables element by element comparison,
  this would lead to remove API made irrelevant like:
  • usingComparatorForElementFieldsWithNames
  • usingComparatorForElementFieldsWithType
  • usingElementComparatorOnFields
• AccessibleObject#isAccessible is deprecated from JDK-9+ #1958
• Replace all the concrete return types on assertions / assumptions / soft assertions entry points with the corresponding Abstract...Assert type to facilitate extension for third-party libraries (similar to Align return types across assertions / assumptions / soft assertions #2173, but using abstract classes instead)
• Standardize ShouldBeEqual #2380
• Add Module assertions and module() navigation method to Class assertions

Any comments, proposals or feedback?

[ishanarora04]

Hey , I would like to start work on few of these elements . Is it still available for grabs ?

[scordio]

@ishanarora04 sure it is! We would need a separate main branch to start merging version 4 topics, but this can be prepared once the first pull request is raised.

[bjhargrave]

* Drop multi-release build in favor of module-only

Does this mean JPMS modules only? We need to continue to support OSGi users. So the osgi-test team would like to work with you to ensure continued OSGi support.

[scordio]

@bjhargrave yes, that point was about JPMS. Working together making sure we are still supporting OSGi users properly would be perfect!

[onacit]

I'm not sure of the schedule but shouldn't Java-8 which is LTS-ish be still count?
Say, I'm the one who is pleased using Assert-J with spring-boot-test which depends itself on assertj-*.
Shouldn't we consider those major frameworks/platforms regarding their plans for Java-11?
Thanks.

[scordio]

There is no schedule yet for AssertJ 4. Version 3 would easily continue along with version 4 for some time and we would backport any Java 8 compatible feature during this overlapping.

[scordio]

As per team's discussion, AssertJ 4 should use/require Java 17.

[scordio]

We'll probably publish milestone and release candidate releases, as we do for assertj-assertions-generator.

[erizzo]

I see there was a first milestone release back in March, 2025 (8 months ago as of the time of this message). I totally understand that a major release can take a lot of time and most of the maintainers are probably working for free or in spare time. But it does make me wonder, has AssertJ 4 bitten off more than can be chewed, so to speak? Should the scope be reduced so that it can actually be delivered? I'd hate for it to turn into another Duke Nukem Forever.

[scordio]

has AssertJ 4 bitten off more than can be chewed, so to speak? Should the scope be reduced so that it can actually be delivered?

There are indeed major topics we'd like to address in version 4, and they do require some effort.

While putting them aside for now would indeed help speed up GA, we would miss the current "breaking change train", which is unlikely to happen again anytime soon (i.e., we don't want to release version 5 a year later). However, I totally understand the point, and we'll do our best to keep things to a minimum, especially for new features that could be easily added on top without a significant redesign of the core parts.

Lastly, just to update this thread, snapshots are now published to Maven Central.

[ascopes]

are there marked issues for deliverables that could be worked on in parallel by the community?

[scordio]

Currently, most of our effort is focused on reducing the number of open PRs and preparing the migration guide from 3.x to 4.0.

We'll make sure to mark with status: ideal for contribution all the topics where the community could jump in!

[jojopad]

How about creating an extension for AssertJ that can be used as a general purpose fluent validation API? I think AssertJ's core API is well suited for such usage.

[scordio]

I'm not sure I understand what you mean. Would you mind adding some details?

[ascopes]

regarding #2639, you'd also want to update the implementation here to support ClassLoader#getName, etc. which were added in JRE 9!

If there is an active branch for AssertJ 4, then I can always cherrypick my changes onto that branch with the new functionality once I complete it?

[scordio]

AssertJ 4 development has not been started yet, but we plan to start working on it soon.

[onacit]

If I may, I want to put another comment.

Can we rebase the whole codebase based on interfaces for clean separation between specifications and implementations? Thanks.

[joel-costigliola]

That's something we want to do indeed.
Do you have specific interface candidates in mind you wish you had?

[onacit]

@joel-costigliola Thank.

I'm not concerning about using the AssertJ but about extending the AssertJ.
No matter how many times I tried to defined a clean interface extending Assert<?, T>, I keep myself falling back to AbstractAssert<?, T>.

I understand there were, are, and will be plenty of reasons of

• Using those Abstract...Assert classes as 1st class citizen
  • for, for an instance, (package-private|protected) variables and methods.
• Defining NumberAssert<SELF, ACTUAL extends Number> or ComparableAssert<SELF, ATUAL extends Comparable<? super ACTUAL>> as not extending Assert<SELF, ACTUAL>.
  • They are not extended types but traits.

When we're going to make the AssertJ4 based on Java 17 which clearly supports JPMS, we can construct a clean type/interface hierarchy and use those abstract/default classes as internal implementations.

interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> {
        // empty
}

interface ObjectAssert<SELF extends Assert<SELF, ACTUAL>, ACTUAL>
        extends Assert<SELF, ACTUAL> {
}

interface NumberAssert<
            SELF extends NumberAssert<SELF, ACTUAL>,
            ACTUAL extends Number>
        extends ObjectAssert<SELF, ACTUAL> {
}

interface ComparableAssert<
            SELF extends ComparableAssert<SELF, ACTUAL>,
            ACTUAL extends Comparable<? super ACTUAL>>
        extends ObjectAssert<SELF, ACTUAL> {
}

interface ComparableAssert<
            SELF extends ComparableAssert<SELF, ACTUAL>,
            ACTUAL extends Comparable<? super ACTUAL>>
        extends ObjectAssert<SELF, ACTUAL> {
}

// trait
interface FloatingPointAssertTrait<
            ASSERT extends Assert<ASSERT> & FloatingPointNumberTrait<ASSERT, ACTUAL>,
            ACTUAL extends Number>
}

// and trait helper
final class FloatingPointAssertTraitHelper {
        // reflections and (method|var) handles
}

public interface FloatAssert<SELF extends FloatAssert<SELF>>
        extends NumberAssert<SELF, Float>,
                      ComparableAssert<SELF, Float>,
                      FloatingPointAssertTrait<SELF, Float> {
}

public abstract class AbstractFloatAssert<SELF extends AbstractFloatAssert<SELF>>
        extends AbstractNumberAssert<SELF, Float>
        implements FloatAssert<SELF> {
}

/* module private */ class FloatAsertImpl
        extends AbstractFloatAssert<FloatAssertImpl> {
}

The points are

• Let developers, who use AssertJ, rely on interfaces
• Let developers, who extends AssertJ, use those extensible abstract classes
• Hide default implementations which may not helping those using nor extending AssertJ.

final float actual = .0f;

// interface not abstract|concrete class
static FloatAssert assertThat(Float actual);

// extensible
static <ASSERT extends FloatAssert> assertThat(Float actual, AssertFactory<? super Float, ? extends ASSERT> factory);

[scordio]

When we're going to make the AssertJ4 based on Java 17 which clearly supports JPMS, we can construct a clean type/interface hierarchy and use those abstract/default classes as internal implementations.

If we wouldn't expose such abstract classes and we would have interfaces only, maybe with default or even private methods, keeping the state needed for the type-related assertions would be a burden we push to the implementors of such interfaces. Or do you have something else in mind?

As a related topic, we might check how private methods in interfaces can help with it but I still feel we cannot have a stateless implementation.

Something that could be clearer from a user experience perspective, also for extension authors, is to drop the Abstract prefix in the class names and also reduce the visibility of the concrete classes to package-private, giving a clear indication that assertion instances should be obtained via entry point methods in Assertions or BDDAssertions.

Hide default implementations which may not helping those using nor extending AssertJ.

I am very much in favor of this. Whenever possible, we should keep these things only with private or package-private visibility.

[scordio]

• Let developers, who use AssertJ, rely on interfaces
• Let developers, who extends AssertJ, use those extensible abstract classes

To continue satisfying the second point, we have to keep the abstract classes as public.

What users from the first point would gain if we would expose additional interfaces? I expect the common usage pattern to be a chain of assertions after an assertThat invocation so most likely there is no local variable holding the instance assertThat returns.

[onacit]

@scordio Thanks.

To continue satisfying the second point, we have to keep the abstract classes as public.

Maybe yes or maybe no.

• We may include interfaces and abstract classes in a single module.
  • The point is that all AssertJ usages may be defined with only those interfaces.
  • Abstract classes are for those extending AssertJ.
• We may separate interfaces and abstract classes into two separated modules.
  • Say, assertj-core and assertj-runtime?

Besides, I just did a quick sketch regarding interface separation.

• May looks somewhat off-road of traditional interface -> abstract class hierarachy.
• Depends on reflection/(method|var)handle

public interface Assert<SELF extends Assert<SELF, ACTUAL>, ACTUAL> {

    default SELF isEqualTo(final Object expected) {
        // delegates operations to the delegate which commune with implementation class
        return AssertHelper.delegate((SELF) this).isEqualTo(expected);
    }
}

interface AssertDelegate<ASSERT extends Assert<ASSERT, ACTUAL>, ACTUAL> {

    ASSERT isEqualTo(final Object expected);
}

abstract class AbstractAssert<SELF extends AbstractAssert<SELF, DELEGATE, ACTUAL>, DELEGATE extends AssertDelegate<SELF, ACTUAL>, ACTUAL>
        implements Assert<SELF, ACTUAL> {

    protected AbstractAssert(final Class<SELF> clazz, final DELEGATE delegate, final ACTUAL actual) {
        super();
        this.clazz = Objects.requireNonNull(clazz, "clazz is null");
        this.actual = actual;
        this.delegate = Objects.requireNonNull(delegate, "delegate is null");
    }

    protected SELF self() {
        return clazz.cast(this);
    }

    private final Class<SELF> clazz;

    private final DELEGATE delegate;

    protected final ACTUAL actual;
}

abstract class AbstractAssertDelegate<ASSERT extends Assert<ASSERT, ACTUAL>, ACTUAL>
        implements AssertDelegate<ASSERT, ACTUAL> {

    AbstractAssertDelegate() {
        super();
    }

    @Override
    public ASSERT isEqualTo(final Object expected) {
        throw new UnsupportedOperationException("not implemented yet");
    }
}

final class AssertHelper {

    static <ASSERT extends Assert<ASSERT, ACTUAL>, ACTUAL> AssertDelegate<ASSERT, ACTUAL> delegate(final ASSERT assertion) {
        Objects.requireNonNull(assertion, "assertion is null");
        try {
            final Field field = AbstractAssert.class.getDeclaredField("delegate");
            field.setAccessible(true);
            return (AssertDelegate<ASSERT, ACTUAL>) field.get(assertion);
        } catch (final ReflectiveOperationException roe) {
            throw new RuntimeException("roe");
        }
    }

    private AssertHelper() {
        throw new AssertionError("instantiation is not allowed");
    }
}

[ascopes]

Is it likely that stuff such as assertThatCode will be deprecated in 4.x.x in favour of using assertThatException and assertThatNoException instead?

[scordio]

No, I don't think so. Once #2519 is finalized, assertThatCode should ideally become a superset of the other two, allowing the following:

  @Test
  void demo() {
    Callable<Boolean> callable = () -> "value".isEmpty();

    // AbstractCallableAssert
    assertThatCode(callable).doesNotThrowAnyException()
                            .result() // returns AbstractObjectAssert
                            .isEqualTo(false);

    // AbstractCallableAssert
    assertThatCode(callable).result(BOOLEAN) // implicit doesNotThrowAnyException()
                            .isFalse();

    // AbstractCallableAssert
    assertThatCode(() -> "value".isEmpty()).doesNotThrowAnyException()
                                           .result()
                                           .isEqualTo(false);

    // AbstractCallableAssert
    assertThatCode(() -> nonVoidThrowingMethod()).hasThrownException() // returns ThrowableAssertAlternative
                                                 .withMessage("Boom!")
                                                 .withNoCause();

    ThrowableAssert.ThrowingCallable assertjThrowingCallable = () -> "value".isEmpty();

    // AbstractThrowableAssert
    assertThatCode(assertjThrowingCallable).doesNotThrowAnyException();

    // AbstractThrowableAssert
    assertThatCode(() -> System.out.println("")).doesNotThrowAnyException();

    // AbstractThrowableAssert
    assertThatCode(() -> voidThrowingMethod()).hasMessage("Boom!");
  }