EqualsVerifier

Additional

Language
Java
Version
equalsverifier-3.15.6 (Jan 9, 2024)
Created
Mar 29, 2015
Updated
Jan 16, 2024
Owner
Jan Ouwens (jqno)
Contributors
Michael Keppler (Bananeweizen)
Jan Ouwens (jqno)
Thomas Matthijs (selckin)
Andrey Turbanov (turbanoff)
Simon Legner (simon04)
Michal Kordas (mkordas)
Stephan Schroevers (Stephan202)
Vincent Privat (don-vip)
Patrick Strawderman (kilink)
dean-allen
Roman Ivanov (romani)
rnveach
Karl Heinz Marbaise (khmarbaise)
Nathan Perdijk (NRBPerdijk)
sullis
Evan Gilbert (eggilbert)
dependabot[bot]
Matt M. (9numbernine9)
Show all (31)31
Activity
Badge
Generate
Download
Source code

EqualsVerifier

EqualsVerifier can be used in Java unit tests to verify whether the contract for the equals and hashCode methods in a class is met.

Getting Started

EqualsVerifier's Maven coordinates are:

<dependency>
    <groupId>nl.jqno.equalsverifier</groupId>
    <artifactId>equalsverifier</artifactId>
    <version>3.15.6</version>
    <scope>test</scope>
</dependency>

(Note that there's also a 'fat' jar with no transitive dependencies with artifactId equalsverifier-nodep.)

Now you can write a test:

@Test
public void equalsContract() {
    EqualsVerifier.forClass(Foo.class).verify();
}

EqualsVerifier is an opinionated library, which means that it can be quite strict. If you feel it's too much, you can make it more lenient:

@Test
public void equalsContract() {
    EqualsVerifier.simple().forClass(Foo.class).verify();
}

This way, EqualsVerifier will throw less errors at you. However, it's usually better to just fix the errors: EqualsVerifier throws them for a reason!

For more information, please see the project's website.

Prefer to watch a short video?

Video by Tom Cools

A note on equality

EqualsVerifier cares about bug-free equality, in Java and in real life. The place where a person happens to be born, the colour of their skin, their gender, or the person they happen to love, must not affect the way they are treated in life. If it does, that's a bug and it should throw an error.

Don't allow bugs in your equality.

????????????‍????‍????????????

Contribution

Pull requests are welcome! If you plan to open one, please also register an issue or send a message to the Google Group, so we can discuss it first. It would be a shame to put in a lot of work on something that isn't a good fit for the project. Also, I can help you by giving pointers on where to find certain things.

Development

Build

To build EqualsVerifier, you need Maven. Just call mvn from the command-line, without any parameters, and you're done. Alternatively, you can use any IDE with Maven support.

There are several Maven profiles that can be enabled or disabled:

profile activation purpose
modules-jdk8 JDK 8 up to but not including 11 Build only the modules that are compatible with Java 8 and up.
modules-jdk11 JDK 11 up to but not including 16 Build only the modules that are compatible with Java 11 and up.
modules-jdk16 JDK 16 Build only the modules that are compatible with Java 16 and up.
modules-jdk17 JDK 17 and up Build all modules and build releaseable artifacts.
static-analysis JDK 17 and up, and disableStaticAnalysis property must be off Run static analysis checks. This only happens on a recent JDK. Can be disabled by running mvn verify -DdisableStaticAnalysis
release-verification JDK 17 and up, and disableReleaseVerification property must be off Run release verification checks. This only happens on a recent JDK. Can be disabled by running mvn verify -DdisableReleaseVerification
argline-preview preview property must be on Enable Java preview features. Can be activated by running mvn verify -Dpreview
argline-experimental experimental property must be on Enables ByteBuddy experimental features; useful for testing EqualsVerifier on Early Access JDK builds. Can be activated by running mvn verify -Dexperimental
pitest pitest property must be on Used by PITest integration on GitHub. Can be activated by running mvn verify -Dpitest

Formatting

EqualsVerifier uses Prettier-Java through prettier-maven-plugin to format Java files. You can call it using mvn clean verify, or run mvn prettier:write to only run the formatter.

Modules

This project is a multi-module project to make it easier to deal with shading and multi-release jar files. See this question on StackOverflow for the rationale behind it.

Here's a description of the modules:

module purpose
docs project's Jekyll website
equalsverifier-core the actual EqualsVerifier code
equalsverifier-11 tests for Java 11 and up
equalsverifier-16 logic for records, and corresponding tests
equalsverifier-17 logic for sealed classes, and corresponding tests
equalsverifier-21 tests for record pattern matching
equalsverifier-aggregator generic release assembly description, and shared jacoco configuration
equalsverifier-release-main release assembly for jar with dependencies
equalsverifier-release-nodep release assembly for fat jar (with dependencies shaded in)
equalsverifier-release-verify validation tests for the releases

Signed JAR

The lib/ folder in the equalsverifier-test-core module contains a local Maven repository containing a signed JAR, used to test potential ClassLoader issues. Here's how to install a JAR into it:

mvn org.apache.maven.plugins:maven-install-plugin:2.3.1:install-file \
                        -Dfile=&lt;path-to-file> -DgroupId=&lt;myGroup> \
                        -DartifactId=&lt;myArtifactId> -Dversion=&lt;myVersion> \
                        -Dpackaging=&lt;myPackaging> -DcreateChecksum=true \
                        -DlocalRepositoryPath=equalsverifier-test-core/lib

The signed JAR itself can be found in this repo.

Website

To generate the website

  • Using Docker: start the server by running docker-compose up or docker compose run jekyll serve.
  • Using Jekyll: install the Ruby 3.x toolchain and run bundle exec jekyll serve --watch

Note that thepage uses the TilburgsAns font but references it from the main site at jqno.nl. In development, it will fall back to a sans-serif font. See the font license here.

Disclaimer

Copyright 2009-2024 Jan Ouwens