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.

  • Constructor Details

    • SingleTypeEqualsVerifierApi

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

    • SingleTypeEqualsVerifierApi

      public SingleTypeEqualsVerifierApi(Class<T> type, EnumSet<Warning> warningsToSuppress, FactoryCache factoryCache, boolean usingGetClass)
      Constructor.
      Parameters:
      type - The class for which the equals method should be tested.
      warningsToSuppress - A list of warnings to suppress in EqualsVerifier.
      factoryCache - Factories that can be used to create values.
      usingGetClass - Whether getClass is used in the implementation of the equals method, instead of an instanceof check.

  • Method Details

    • 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.

    • 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.
      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.

    • 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:

    • 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.

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

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.
      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.

    • 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.
      See Also:

    • withResetCaches

      public SingleTypeEqualsVerifierApi<T> withResetCaches()
      Signals that all internal caches need to be reset. This is useful when the test framework uses multiple ClassLoaders to run tests, causing Class instances that would normally be equal, to be unequal, because their ClassLoaders don't match.
      Specified by:
      withResetCaches in interface EqualsVerifierApi<T>
      Returns:
      this, for easy method chaining.

    • 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.

    • 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.

    • report

      public EqualsVerifierReport report(boolean showUrl)