JPA entities

EqualsVerifier has support for JPA entities.


JPA entities are mutable by design. Since adding .suppress(Warning.NONFINAL_FIELDS) to each test can get cumbersome, EqualsVerifier will do this implicitly for each class marked with an @Entity, @Embeddable or @MappedSuperclass annotation.

JPA entities are also not allowed to be final, and even a final equals or hashCode method is problematic. Therefore, EqualsVerifier will not enforce these for JPA entities, like it normally would. Note that this means that your class will be vulnerable to subclasses breaking equals.


By default, EqualsVerifier assumes that your entities have a business or natural key. Consequently, all fields that are marked with the @Id annotation are assumed not to participate in the class’s equals and hashCode methods. For all other fields, EqualsVerifier behaves as usual.

EqualsVerifier also supports Hibernate’s @NaturalId annotation. If it detects the presence of this annotation in a class, it will assume that only the fields marked with @NaturalId participate in equals and hashCode, and that all other fields (including the ones marked with @Id) do not.

If your class has a surrogate key, you can tell EqualsVerifier by suppressing Warning.SURROGATE_KEY. When this warning is suppressed, EqualsVerifier assumes that only the field or fields marked with @Id participate in equals and hashCode, and that none of the other fields do.

When @NaturalId is present or when Warning.SURROGATE_KEY is suppressed, there is no need to call #withOnlyTheseFields or #withIgnoredFields.

EqualsVerifier will not only detect these annotations when they are placed on a field, but also when they are placed on the field’s corresponding accessor method.

If your class has a business key, but no separate field to serve as @Id, you can tell EqualsVerifier by suppressing Warning.SURROGATE_OR_BUSINESS_KEY. For instance, if your entity models a person, and the field socialSecurityNumber is marked with @Id, you can use Warning.SURROGATE_OR_BUSINESS_KEY to include socialSecurityNumber and other fields like name and birthDate in equals and hashCode.

In order to meet the consistency requirements when implementing a class with a surrogate key, some argue that it is necessary to make the hashCode constant. EqualsVerifier still requires a ‘normal’ hashCode implementation. If you want a constant hashCode, you can suppress Warning.STRICT_HASHCODE.

Ids and new objects

A common pattern in JPA when deciding whether two objects are equal, is to look at their fields only if the object hasn’t been persisted yet. If it has been persisted, the field has an id, and then the fields are ignored and only the id is used to decide. Such an equals method might look like this:

public boolean equals(Object obj) {
    if (!(obj instanceof Foo)) {
        return false;
    Foo other = (Foo)obj;
    if (id == 0L && == 0L) {
        return super.equals(obj);
    return id ==;

You might see an error message such as this one:

Reflexivity: object does not equal an identical copy of itself:
If this is intentional, consider suppressing Warning.IDENTICAL_COPY

In that case, you can call suppress(Warning.IDENTICAL_COPY_FOR_VERSIONED_ENTITY).

(Warning.IDENTICAL_COPY, which the error message suggests, is not appropriate in this case because that is meant for classes which have no state at all.)

Materialized fields

Some fields have a mapping annotation that links them with data from a different database table or entity. These annotations include @OneToMany, @ManyToOne and @ManyToMany. In certain situations, you can have an instance where these fields are not materialized yet. In other words, they’re not fetched from the database, and their content is undefined. Most often, this happens when they have fetchType = FetchType.LAZY, but even with FetchType.EAGER, it can happen that they are not yet materialized. This also applies to fields with @Basic(fetchType = FetchType.LAZY). JPA will materialize this data on demand. For example, when the getter for such a field is called, JPA is triggered and queries the data. However, this trigger does not happen when the field is referenced directly.

Therefore, when these fields are used in equals and hashCode, it’s important to call their getter method instead of referencing the field directly. Otherwise, the data may not be materialized, and it’s possible that calling equals on two equal objects returns false, because one instance doesn’t have the content yet while the other does.

EqualsVerifier checks for these fields that their getter is used. If they’re referenced directly, EqualsVerifier will fail. Note that this can be disabled by suppressing Warning.JPA_GETTER.

By default, EqualsVerifier assumes that the JavaBeans conventions are used to determine the name of the getter. For example, if a field is called employee, it assumes that the getter is called getEmployee(). If your project uses a different convention, you can use #withFieldnameToGetterConverter() to override that behavior.

For example, if in your project, a field must have a prefix, like so: m_employee, but the getter is still getEmployee(), you might call EqualsVerifier like this:

        fn -> "get" + Character.toUpperCase(fn.charAt(2)) + fn.substring(3)

This will chop off the m_ prefix, uppercase the first letter, and prepend the word get.

Transient fields

Since fields marked with the @Transient annotation are not persisted, they should generally not participate in equals and hashCode either. Therefore, EqualsVerifier will implicitly call withIgnoredFields for these fields.

If they do participate, EqualsVerifier will fail the test. This behavior can be avoided by suppressing Warning.TRANSIENT_FIELDS.

Abstract superclass

A frequent pattern is to have an abstract superclass for all entities, and implement equals and hashCode there for all concrete entity implementations. Usually the objects are compared by their ids only. The fields are left out of the comparison, even is the object is new.

In that case, the easiest way to make it work, is by making the equals and hashCode methods in the abstract class final, like this:

abstract class AbstractEntity {
    private Long id;

    public Long getId() {
        return id;

    public final boolean equals(Object obj) {
        if (!(obj instanceof AbstractEntity)) {
            return false;
        return Objects.equals(getId(), ((AbstractEntity)obj).getId());

    public final int hashCode() {
        return Objects.hashCode(getId());

class Foo extends AbstractEntity {
    private String name;

You don’t have to tell EqualsVerifier anything about inheritance this way. You do have to tell it to only inspect id when testing Foo, though:

public void testAbstractEntity() {

public void testFoo() {

If you want to have an abstract superclass implementing equals, but also include the subclass’s fields in it, I recommend reading the page about inheritance and taking it from there.

Disabling JPA checking

If, for some reason, you don’t want EqualsVerifier to look at JPA’s annotations, you can disable them like this:

        .withIgnoredAnnotations(Entity.class, Id.class, Embeddable.class, MappedSuperclass.class, Transient.class)

Of course, you only need to include the annotations that you actually use. If any of the classes you specify isn’t an annotation, EqualsVerifier throws an exception.