Module nl.jqno.equalsverifier
Package nl.jqno.equalsverifier.api

Class SingleTypeEqualsVerifierApi<T>

java.lang.Object
nl.jqno.equalsverifier.api.SingleTypeEqualsVerifierApi<T>
Type Parameters:
T - The class under test.
All Implemented Interfaces:
EqualsVerifierApi<T>
public class SingleTypeEqualsVerifierApi<T> extends Object implements EqualsVerifierApi<T>
Helps to construct an EqualsVerifier test with a fluent API.
Since:
3.2

  • Field Details

    • type

      private final Class<T> type

    • actualFields

      private final Set<String> actualFields

    • instanceFactory

      private InstanceFactory<T> instanceFactory

    • subclassInstanceFactory

      private InstanceFactory<? extends T> subclassInstanceFactory

    • warningsToSuppress

      private EnumSet<Warning> warningsToSuppress

    • modesToSet

      private Set<Mode> modesToSet

    • usingGetClass

      private boolean usingGetClass

    • hasRedefinedSuperclass

      private boolean hasRedefinedSuperclass

    • redefinedSuperclassInstanceFactory

      private InstanceFactory<?> redefinedSuperclassInstanceFactory

    • redefinedSubclass

      private Class<? extends T> redefinedSubclass

    • redefinedSubclassInstanceFactory

      private InstanceFactory<? extends T> redefinedSubclassInstanceFactory

    • userPrefabs

      private UserPrefabValueCaches userPrefabs

    • fieldCache

      private FieldCache fieldCache

    • cachedHashCodeInitializer

      private CachedHashCodeInitializer<T> cachedHashCodeInitializer

    • fieldnameToGetter

      private Function<String,String> fieldnameToGetter

    • allExcludedFields

      private Set<String> allExcludedFields

    • allIncludedFields

      private Set<String> allIncludedFields

    • nonnullFields

      private Set<String> nonnullFields

    • ignoredAnnotationClassNames

      private Set<String> ignoredAnnotationClassNames

    • equalExamples

      private List<T> equalExamples

    • unequalExamples

      private List<T> unequalExamples

    • objenesis

      private final org.objenesis.Objenesis objenesis

  • Constructor Details

    • SingleTypeEqualsVerifierApi

      public SingleTypeEqualsVerifierApi(Class<T> type)
      Constructor.
      Parameters:
      type - The class for which the equals method should be tested.
      Since:
      3.2

    • SingleTypeEqualsVerifierApi

      private SingleTypeEqualsVerifierApi(Class<T> type, org.objenesis.Objenesis objenesis)
      Constructor.
      Parameters:
      type - The class for which the equals method should be tested.
      objenesis - To instantiate non-record classes.

    • SingleTypeEqualsVerifierApi

      SingleTypeEqualsVerifierApi(Class<T> type, EnumSet<Warning> warningsToSuppress, Set<Mode> modes, UserPrefabValueCaches userPrefabs, org.objenesis.Objenesis objenesis, boolean usingGetClass, Function<String,String> converter)
      Constructor.
      Parameters:
      type - The class for which the equals method should be tested.
      warningsToSuppress - A list of warnings to suppress in EqualsVerifier.
      modes - A set of modes in which EqualsVerifier should operate.
      userPrefabs - Prefab values provided by the user.
      objenesis - To instantiate non-record classes.
      usingGetClass - Whether getClass is used in the implementation of the equals method, instead of an instanceof check.
      converter - A function that converts from field name to getter name.

    • SingleTypeEqualsVerifierApi

      SingleTypeEqualsVerifierApi(Class<T> type, List<T> equalExamples, List<T> unequalExamples)
      Constructor, only to be called by RelaxedEqualsVerifierApi.andUnequalExamples(Object, Object[]).

  • Method Details

    • withFactory

      public SingleTypeEqualsVerifierApi<T> withFactory(InstanceFactory<T> factory)
      Provides a factory for the class under test, in case EqualsVerifier is unable to instantiate it without help. This becomes useful in Java 26 where JEP 500 ("final means final") is active.
      Parameters:
      factory - A factory that can instantiate the class under test.
      Returns:
      this, for easy method chaining.
      Since:
      4.4

    • withFactory

      public SingleTypeEqualsVerifierApi<T> withFactory(InstanceFactory<T> factory, InstanceFactory<? extends T> subclassFactory)
      Provides a factory for the class under test, in case EqualsVerifier is unable to instantiate it without help, as well as a factory for a subclass of the class under test. This is needed when the class under test is non-final, so EqualsVerifier can check the interaction with subclasses. This becomes useful in Java 26 where JEP 500 ("final means final") is active.
      Parameters:
      factory - A factory that can instantiate the class under test.
      subclassFactory - A factory that can instantiate a subclass of the class under test.
      Returns:
      this, for easy method chaining.
      Since:
      4.4

    • suppress

      public SingleTypeEqualsVerifierApi<T> suppress(Warning... warnings)
      Suppresses warnings given by EqualsVerifier. See Warning to see what warnings can be suppressed.
      Specified by:
      suppress in interface EqualsVerifierApi<T>
      Parameters:
      warnings - A list of warnings to suppress in EqualsVerifier.
      Returns:
      this, for easy method chaining.

    • set

      public SingleTypeEqualsVerifierApi<T> set(Mode... modes)
      Sets modes that influence how EqualsVerifier operates.}
      Specified by:
      set in interface EqualsVerifierApi<T>
      Parameters:
      modes - A list of modes to influence how EqualsVerifier operates.
      Returns:
      this, for easy method chaining.

    • withPrefabValues

      public <S> SingleTypeEqualsVerifierApi<T> withPrefabValues(Class<S> otherType, S red, S blue)
      Adds prefabricated values for instance fields of classes that EqualsVerifier cannot instantiate by itself. This overload will attempt to copy red. If that fails, use the other overload.
      Specified by:
      withPrefabValues in interface EqualsVerifierApi<T>
      Type Parameters:
      S - The class of the prefabricated values.
      Parameters:
      otherType - The class of the prefabricated values.
      red - An instance of S.
      blue - Another instance of S, not equal to red.
      Returns:
      this, for easy method chaining.

    • withPrefabValues

      public <S> SingleTypeEqualsVerifierApi<T> withPrefabValues(Class<S> otherType, S red, S blue, S redCopy)
      Adds prefabricated values for instance fields of classes that EqualsVerifier cannot instantiate by itself.
      Specified by:
      withPrefabValues in interface EqualsVerifierApi<T>
      Type Parameters:
      S - The class of the prefabricated values.
      Parameters:
      otherType - The class of the prefabricated values.
      red - An instance of S.
      blue - Another instance of S, not equal to red.
      redCopy - A copy of red.
      Returns:
      this, for easy method chaining.

    • withResettablePrefabValues

      public <S> SingleTypeEqualsVerifierApi<T> withResettablePrefabValues(Class<S> otherType, Supplier<S> red, Supplier<S> blue)
      Adds Suppliers for resettable prefabricated values for instance fields of classes that EqualsVerifier cannot instantiate by itself. Resettable values are values that are created new every time a new instance of T is constructed within EqualsVerifier. This can be useful when T mutates its instances of S.
      Specified by:
      withResettablePrefabValues in interface EqualsVerifierApi<T>
      Type Parameters:
      S - The class of the prefabricated values.
      Parameters:
      otherType - The class of the prefabricated values.
      red - An instance of S.
      blue - Another instance of S, not equal to red.
      Returns:
      this, for easy method chaining.

    • withPrefabValuesForField

      public <S> SingleTypeEqualsVerifierApi<T> withPrefabValuesForField(String fieldName, S red, S blue)
      Adds prefabricated values for instance fields with a given name (and only the fields with the given name) that EqualsVerifier cannot instantiate by itself. This overload will attempt to copy red. If that fails, use the other overload.
      Type Parameters:
      S - The class of the prefabricated values.
      Parameters:
      fieldName - The name of the field that the prefabricated values are linked to.
      red - An instance of S.
      blue - Another instance of S, not equal to red.
      Returns:
      this, for easy method chaining.
      Throws:
      NullPointerException - If red or blue is null, or if the named field does not exist in the class.
      IllegalArgumentException - If red equals blue.
      Since:
      3.17

    • withPrefabValuesForField

      public <S> SingleTypeEqualsVerifierApi<T> withPrefabValuesForField(String fieldName, S red, S blue, S redCopy)
      Adds prefabricated values for instance fields with a given name (and only the fields with the given name) that EqualsVerifier cannot instantiate by itself.
      Type Parameters:
      S - The class of the prefabricated values.
      Parameters:
      fieldName - The name of the field that the prefabricated values are linked to.
      red - An instance of S.
      blue - Another instance of S, not equal to red.
      redCopy - A copy of red.
      Returns:
      this, for easy method chaining.
      Throws:
      NullPointerException - If red or blue is null, or if the named field does not exist in the class.
      IllegalArgumentException - If red equals blue.
      Since:
      4.4

    • withGenericPrefabValues

      public <S> SingleTypeEqualsVerifierApi<T> withGenericPrefabValues(Class<S> otherType, Func.Func1<?,S> factory)
      Adds a factory to generate prefabricated values for instance fields of classes with 1 generic type parameter that EqualsVerifier cannot instantiate by itself.
      Specified by:
      withGenericPrefabValues in interface EqualsVerifierApi<T>
      Type Parameters:
      S - The class of the prefabricated values.
      Parameters:
      otherType - The class of the prefabricated values.
      factory - A factory to generate an instance of S, given a value of its generic type parameter.
      Returns:
      this, for easy method chaining.

    • withGenericPrefabValues

      public <S> SingleTypeEqualsVerifierApi<T> withGenericPrefabValues(Class<S> otherType, Func.Func2<?,?,S> factory)
      Adds a factory to generate prefabricated values for instance fields of classes with 2 generic type parameters that EqualsVerifier cannot instantiate by itself.
      Specified by:
      withGenericPrefabValues in interface EqualsVerifierApi<T>
      Type Parameters:
      S - The class of the prefabricated values.
      Parameters:
      otherType - The class of the prefabricated values.
      factory - A factory to generate an instance of S, given a value of each of its generic type parameters.
      Returns:
      this, for easy method chaining.

    • usingGetClass

      public SingleTypeEqualsVerifierApi<T> usingGetClass()
      Signals that getClass is used in the implementation of the equals method, instead of an instanceof check.
      Specified by:
      usingGetClass in interface EqualsVerifierApi<T>
      Returns:
      this, for easy method chaining.
      See Also:

    • withFieldnameToGetterConverter

      public SingleTypeEqualsVerifierApi<T> withFieldnameToGetterConverter(Function<String,String> converter)
      Determines how a getter name can be derived from a field name. The default behavior is to uppercase the field's first letter and prepend 'get'. For instance, a field name 'employee' would correspond to getter name 'getEmployee'. This method can be used if your project has a different naming convention.
      Specified by:
      withFieldnameToGetterConverter in interface EqualsVerifierApi<T>
      Parameters:
      converter - A function that converts from field name to getter name.
      Returns:
      this, for easy method chaining.

    • withIgnoredFields

      public SingleTypeEqualsVerifierApi<T> withIgnoredFields(String... fields)
      Signals that all given fields are not relevant for the equals contract. EqualsVerifier will not fail if one of these fields does not affect the outcome of equals, but it will fail if one of these fields does affect the outcome of equals.

      Note that these fields will still be used to test for null-ness, among other things. Therefore, EqualsVerifier needs values for these fields, and will ask for prefab values if it can't make them.

      Parameters:
      fields - Fields that should be ignored.
      Returns:
      this, for easy method chaining.
      Since:
      2.0

    • withOnlyTheseFields

      public SingleTypeEqualsVerifierApi<T> withOnlyTheseFields(String... fields)
      Signals that all given fields, and only the given fields, are relevant for the equals contract. EqualsVerifier will fail if one of these fields does not affect the outcome of equals, and it will fail if a field that isn't listed here, does affect the outcome of equals.
      Parameters:
      fields - Fields that should be ignored.
      Returns:
      this, for easy method chaining.
      Since:
      2.0

    • withFieldsAddedAndValidated

      private SingleTypeEqualsVerifierApi<T> withFieldsAddedAndValidated(Set<String> collection, List<String> specifiedFields)

    • withNonnullFields

      public SingleTypeEqualsVerifierApi<T> withNonnullFields(String... fields)
      Signals that all given fields can never be null, and EqualsVerifier therefore doesn't have to verify that proper null checks are in place for these fields.

      This can be used instead of {link #suppress(Warning...)}, which provides the same behaviour for all fields, when only some fields are never null but others are.

      Parameters:
      fields - Fields that can never be null.
      Returns:
      this, for easy method chaining.
      Since:
      2.2

    • withIgnoredAnnotations

      public SingleTypeEqualsVerifierApi<T> withIgnoredAnnotations(Class<?>... annotations)
      Signals that all given annotations are to be ignored by EqualsVerifier.

      For instance, EqualsVerifier normally doesn't perform null verifications on fields marked with an @Nonnull annotation. However, if this method is called with a Nonnull.class parameter, the null verifications will be performed after all.

      Parameters:
      annotations - Annotations to ignore.
      Returns:
      this, for easy method chaining.
      Since:
      2.3

    • withRedefinedSuperclass

      public SingleTypeEqualsVerifierApi<T> withRedefinedSuperclass()
      Signals that T is part of an inheritance hierarchy where equals is overridden. Call this method if T has overridden equals and hashCode, and one or more of T's superclasses have as well.

      T itself does not necessarily have to have subclasses that redefine equals and hashCode.

      Returns:
      this, for easy method chaining.
      Since:
      0.6

    • withRedefinedSuperclass

      public SingleTypeEqualsVerifierApi<T> withRedefinedSuperclass(InstanceFactory<?> superclassFactory)
      Signals that T is part of an inheritance hierarchy where equals is overridden. Call this method if T has overridden equals and hashCode, and one or more of T's superclasses have as well.

      Provides a factory for the superclass, in case EqualsVerifier is unable to instantiate it without help. This becomes useful in Java 26 where JEP 500 ("final means final") is active.

      T itself does not necessarily have to have subclasses that redefine equals and hashCode.

      Parameters:
      superclassFactory - A factory that can instantiate the direct superclass of the class under test.
      Returns:
      this, for easy method chaining.
      Since:
      4.4

    • withRedefinedSubclass

      public SingleTypeEqualsVerifierApi<T> withRedefinedSubclass(Class<? extends T> subclass)
      Supplies a reference to a subclass of T in which equals is overridden. Calling this method is mandatory if equals is not final and a strong verification is performed.

      Note that, for each subclass that overrides equals, EqualsVerifier should be used as well to verify its adherence to the contracts.

      Parameters:
      subclass - A subclass of T for which no instance can be equal to any instance of T.
      Returns:
      this, for easy method chaining.
      Since:
      0.1
      See Also:

    • withRedefinedSubclass

      public SingleTypeEqualsVerifierApi<T> withRedefinedSubclass(InstanceFactory<? extends T> subclassFactory)
      Supplies a factory for a subclass of T in which equals is overridden. Calling this method is mandatory if equals is not final and a strong verification is performed.

      This becomes useful in Java 26 where JEP 500 ("final means final") is active.

      Note that, for each subclass that overrides equals, EqualsVerifier should be used as well to verify its adherence to the contracts.

      Parameters:
      subclassFactory - A factory that can instantiate a subclass of T for which no instance can be equal to any instance of T.
      Returns:
      this, for easy method chaining.
      Since:
      4.4
      See Also:

    • withCachedHashCode

      public SingleTypeEqualsVerifierApi<T> withCachedHashCode(String cachedHashCodeField, String calculateHashCodeMethod, T example)
      Signals that T caches its hashCode, instead of re-calculating it each time the hashCode() method is called.

      There are 3 conditions to verify cached hashCodes:

      First, the class under test must have a private int field that contains the cached hashCode.

      Second, the class under test must have a private method that calculates the hashCode. The method must return an int and may not take any parameters. It should be used by the constructor or the hashCode method of the class under test to initialize the cached hashCode. This may lead to slightly awkward production code, but unfortunately, it is necessary for EqualsVerifier to verify that the hashCode is correct.

      Finally, only immutable objects can be verified. In other words, withCachedHashCode can not be used when Warning.NONFINAL_FIELDS is suppressed.

      Parameters:
      cachedHashCodeField - The name of the field which stores the cached hash code.
      calculateHashCodeMethod - The name of the method which recomputes the hash code. It should return an int and take no parameters.
      example - An instance of the class under test, to verify that the hashCode has been initialized properly.
      Returns:
      this, for easy method chaining.
      Since:
      1.7

    • withLombokCachedHashCode

      public SingleTypeEqualsVerifierApi<T> withLombokCachedHashCode(T example)
      Signals that T uses Lombok to cache its hashCode, instead of re-calculating it each time the hashCode() method is called.
      Parameters:
      example - An instance of the class under test, to verify that the hashCode has been initialized properly.
      Returns:
      this, for easy method chaining.
      Since:
      3.7
      See Also:

    • verify

      public void verify()
      Performs the verification of the contracts for equals and hashCode and throws an AssertionError if there is a problem.
      Throws:
      AssertionError - If the contract is not met, or if EqualsVerifier's preconditions do not hold.
      Since:
      0.1

    • report

      public EqualsVerifierReport report()
      Performs the verification of the contracts for equals and hashCode and returns an EqualsVerifierReport with the results of the verification.
      Returns:
      An EqualsVerifierReport that indicates whether the contract is met and whether EqualsVerifier's preconditions hold.
      Since:
      3.0

    • report

      public EqualsVerifierReport report(boolean showUrl)
      Performs the verification of the contracts for equals and hashCode and returns an EqualsVerifierReport with the results of the verification.
      Parameters:
      showUrl - Whether or not to show the url at the end of the error message.
      Returns:
      An EqualsVerifierReport that indicates whether the contract is met and whether EqualsVerifier's preconditions hold.
      Since:
      3.2

    • buildErrorMessage

      private String buildErrorMessage(String description, boolean showUrl)

    • performVerification

      private void performVerification()

    • buildConfig

      private Configuration<T> buildConfig()

    • verifyWithoutExamples

      private void verifyWithoutExamples(Context<T> context)

    • verifyWithExamples

      private void verifyWithExamples(Context<T> context)