0
# EqualsVerifier
1

2
EqualsVerifier is a Java library that verifies whether the contract for the equals and hashCode methods in a class is met. It provides extensive testing capabilities including contract verification, null safety checking, symmetry and transitivity testing, and coverage of edge cases like inheritance hierarchies and complex field types.
3

4
## Package Information
5

6
- **Package Name**: nl.jqno.equalsverifier:equalsverifier
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven: `<dependency><groupId>nl.jqno.equalsverifier</groupId><artifactId>equalsverifier</artifactId><version>3.17.5</version><scope>test</scope></dependency>`
10

11
## Core Imports
12

13
```java
14
import nl.jqno.equalsverifier.EqualsVerifier;
15
import nl.jqno.equalsverifier.Warning;
16
```
17

18
## Basic Usage
19

20
```java
21
import nl.jqno.equalsverifier.EqualsVerifier;
22

23
public class PersonTest {
24
    @Test
25
    public void testEquals() {
26
        EqualsVerifier.forClass(Person.class).verify();
27
    }
28
    
29
    @Test 
30
    public void testEqualsWithSimpleConfiguration() {
31
        EqualsVerifier.simple()
32
            .forClass(Person.class)
33
            .verify();
34
    }
35
}
36
```
37

38
## Architecture
39

40
EqualsVerifier is built around several key patterns:
41

42
- **Fluent API**: Method chaining interface for configuration and execution
43
- **Factory Pattern**: Static factory methods for different verification scenarios  
44
- **Builder Pattern**: Incremental configuration of verification parameters
45
- **Strategy Pattern**: Warning suppression system for different validation rules
46
- **Template Method**: Base verification process with customizable steps
47

48
## Capabilities
49

50
### Single Class Verification
51

52
Core functionality for verifying equals and hashCode contracts for individual classes. Supports extensive configuration options for field handling, warning suppression, and inheritance scenarios.
53

54
```java { .api }
55
public static <T> SingleTypeEqualsVerifierApi<T> forClass(Class<T> type);
56

57
public static ConfiguredEqualsVerifier simple();
58
```
59

60
[Single Class API](./single-class-api.md)
61

62
### Multiple Class Verification
63

64
Batch verification capabilities for testing multiple classes with shared configuration. Supports package scanning, filtering, and exception handling for large codebases.
65

66
```java { .api }
67
public static MultipleTypeEqualsVerifierApi forClasses(
68
    Iterable<Class<?>> classes
69
);
70

71
public static MultipleTypeEqualsVerifierApi forClasses(
72
    Class<?> first, 
73
    Class<?> second, 
74
    Class<?>... more
75
);
76

77
public static MultipleTypeEqualsVerifierApi forPackage(String packageName);
78
```
79

80
[Multiple Class API](./multiple-class-api.md)
81

82
### Configuration and Reuse
83

84
Reusable configuration objects that can be applied across multiple verification scenarios. Enables consistent testing patterns and shared prefab values.
85

86
```java { .api }
87
public static ConfiguredEqualsVerifier configure();
88

89
public final class ConfiguredEqualsVerifier implements EqualsVerifierApi<Void> {
90
    public ConfiguredEqualsVerifier suppress(Warning... warnings);
91
    public <S> ConfiguredEqualsVerifier withPrefabValues(
92
        Class<S> otherType, 
93
        S red, 
94
        S blue
95
    );
96
}
97
```
98

99
[Configuration API](./configuration-api.md)
100

101
### Relaxed Equality Verification
102

103
Specialized verification for classes with relaxed equality rules where multiple instances can be equal despite different internal state. Common in normalized representations and value objects.
104

105
```java { .api }
106
@SafeVarargs
107
public static <T> RelaxedEqualsVerifierApi<T> forRelaxedEqualExamples(
108
    T first,
109
    T second,
110
    T... more
111
);
112

113
public final class RelaxedEqualsVerifierApi<T> {
114
    public SingleTypeEqualsVerifierApi<T> andUnequalExample(T example);
115
    @SafeVarargs
116
    public final SingleTypeEqualsVerifierApi<T> andUnequalExamples(
117
        T first, 
118
        T... more
119
    );
120
}
121
```
122

123
[Relaxed Equality API](./relaxed-equality-api.md)
124

125
### Warning Suppression System
126

127
Comprehensive warning system for suppressing specific validation rules when they don't apply to particular use cases. Includes warnings for inheritance, field usage, JPA entities, and more.
128

129
```java { .api }
130
public enum Warning {
131
    STRICT_INHERITANCE,
132
    NONFINAL_FIELDS,
133
    NULL_FIELDS,
134
    ALL_FIELDS_SHOULD_BE_USED,
135
    REFERENCE_EQUALITY,
136
    // ... 17 total warning types
137
}
138
```
139

140
[Warning System](./warning-system.md)
141

142
## Types
143

144
```java { .api }
145
public final class EqualsVerifierReport {
146
    public Class<?> getType();
147
    public boolean isSuccessful();
148
    public String getMessage();
149
    public Throwable getCause();
150
    
151
    public static EqualsVerifierReport success(Class<?> type);
152
    public static EqualsVerifierReport failure(
153
        Class<?> type, 
154
        String message, 
155
        Throwable cause
156
    );
157
}
158

159
/**
160
 * Functional interface for generating prefab values of some generic type T.
161
 * For each generic type parameter for T, a value of that type will be supplied in the
162
 * List parameter of apply(List).
163
 */
164
@FunctionalInterface
165
public interface Func<T> {
166
    T apply(List<?> values);
167
}
168

169
/**
170
 * Functional interface for generating prefab values of a generic type T that has
171
 * exactly 1 generic parameter A.
172
 * A value of A will be supplied in the supply(Object) method.
173
 */
174
@SuppressWarnings("unchecked")
175
@FunctionalInterface
176
public interface Func1<A, T> extends Func<T> {
177
    @Override
178
    default T apply(List<?> values) {
179
        return supply((A) values.get(0));
180
    }
181
    
182
    T supply(A a);
183
}
184

185
/**
186
 * Functional interface for generating prefab values of a generic type T that has
187
 * exactly 2 generic parameters, A and B.
188
 * Values of A and B will be supplied in the supply(Object, Object) method.
189
 */
190
@SuppressWarnings("unchecked")
191
@FunctionalInterface 
192
public interface Func2<A, B, T> extends Func<T> {
193
    @Override
194
    default T apply(List<?> values) {
195
        return supply((A) values.get(0), (B) values.get(1));
196
    }
197
    
198
    T supply(A a, B b);
199
}
200
```