0
# Configuration API
1

2
Reusable configuration objects that can be applied across multiple verification scenarios. The `ConfiguredEqualsVerifier` enables consistent testing patterns and shared prefab values across different classes and verification contexts.
3

4
## Capabilities
5

6
### Configuration Creation
7

8
Creates reusable configuration objects with fluent API.
9

10
```java { .api }
11
/**
12
 * Creates a configuration object that can be reused with EqualsVerifier for multiple classes.
13
 * It has a fluent API.
14
 * @return A reusable configuration object with a fluent API
15
 */
16
public static ConfiguredEqualsVerifier configure();
17

18
/**
19
 * Creates a configuration object that is pre-configured so that it can be used with most
20
 * IDE-generated equals and hashCode methods without any further configuration.
21
 * @return A reusable configuration object with a fluent API
22
 */
23
public static ConfiguredEqualsVerifier simple();
24
```
25

26
**Usage Examples:**
27

28
```java
29
import nl.jqno.equalsverifier.EqualsVerifier;
30
import nl.jqno.equalsverifier.ConfiguredEqualsVerifier;
31

32
// Create basic configuration
33
ConfiguredEqualsVerifier config = EqualsVerifier.configure()
34
    .suppress(Warning.STRICT_INHERITANCE)
35
    .withPrefabValues(ExternalDependency.class, redValue, blueValue);
36

37
// Create simple pre-configured setup
38
ConfiguredEqualsVerifier simpleConfig = EqualsVerifier.simple()
39
    .withPrefabValues(Database.class, mockDb1, mockDb2);
40
```
41

42
### Configuration Management
43

44
Manages and copies configuration objects.
45

46
```java { .api }
47
/**
48
 * Default constructor for creating new configuration
49
 */
50
public ConfiguredEqualsVerifier();
51

52
/**
53
 * Returns a copy of the configuration
54
 * @return a copy of the configuration
55
 */
56
public ConfiguredEqualsVerifier copy();
57
```
58

59
**Usage Examples:**
60

61
```java
62
// Create base configuration
63
ConfiguredEqualsVerifier baseConfig = EqualsVerifier.configure()
64
    .suppress(Warning.STRICT_INHERITANCE);
65

66
// Create variations of the base configuration
67
ConfiguredEqualsVerifier entityConfig = baseConfig.copy()
68
    .suppress(Warning.SURROGATE_KEY);
69

70
ConfiguredEqualsVerifier dtoConfig = baseConfig.copy()
71
    .suppress(Warning.NONFINAL_FIELDS);
72
```
73

74
### Warning Suppression
75

76
Configures which warnings to suppress across multiple verifications.
77

78
```java { .api }
79
/**
80
 * Suppresses warnings given by EqualsVerifier. See Warning to see what warnings can be suppressed.
81
 * @param warnings A list of warnings to suppress in EqualsVerifier
82
 * @return this, for easy method chaining
83
 */
84
public ConfiguredEqualsVerifier suppress(Warning... warnings);
85
```
86

87
**Usage Examples:**
88

89
```java
90
// Suppress multiple warnings
91
ConfiguredEqualsVerifier config = EqualsVerifier.configure()
92
    .suppress(Warning.STRICT_INHERITANCE, Warning.NONFINAL_FIELDS, Warning.NULL_FIELDS);
93

94
// Conditional warning suppression
95
ConfiguredEqualsVerifier.Builder configBuilder = EqualsVerifier.configure();
96
if (isLegacyCodebase()) {
97
    configBuilder.suppress(Warning.STRICT_HASHCODE);
98
}
99
ConfiguredEqualsVerifier config = configBuilder;
100
```
101

102
### Prefab Value Configuration
103

104
Configures prefabricated values that will be used across multiple class verifications.
105

106
```java { .api }
107
/**
108
 * Adds prefabricated values for instance fields of classes that EqualsVerifier cannot
109
 * instantiate by itself
110
 * @param otherType The class of the prefabricated values
111
 * @param red An instance of S
112
 * @param blue Another instance of S, not equal to red
113
 * @return this, for easy method chaining
114
 */
115
public <S> ConfiguredEqualsVerifier withPrefabValues(
116
    Class<S> otherType, 
117
    S red, 
118
    S blue
119
);
120

121
/**
122
 * Adds a factory to generate prefabricated values for instance fields of classes with 1 generic
123
 * type parameter that EqualsVerifier cannot instantiate by itself
124
 * @param otherType The class of the prefabricated values
125
 * @param factory A factory to generate an instance of S, given a value of its generic type parameter
126
 * @return this, for easy method chaining
127
 */
128
public <S> ConfiguredEqualsVerifier withGenericPrefabValues(
129
    Class<S> otherType, 
130
    Func1<?, S> factory
131
);
132

133
/**
134
 * Adds a factory to generate prefabricated values for instance fields of classes with 2 generic
135
 * type parameters that EqualsVerifier cannot instantiate by itself
136
 * @param otherType The class of the prefabricated values
137
 * @param factory A factory to generate an instance of S, given values of its generic type parameters
138
 * @return this, for easy method chaining
139
 */
140
public <S> ConfiguredEqualsVerifier withGenericPrefabValues(
141
    Class<S> otherType, 
142
    Func2<?, ?, S> factory
143
);
144
```
145

146
**Usage Examples:**
147

148
```java
149
// Configure prefab values for complex types
150
ConfiguredEqualsVerifier config = EqualsVerifier.configure()
151
    .withPrefabValues(ExternalService.class, mockService1, mockService2)
152
    .withPrefabValues(Database.class, testDb1, testDb2)
153
    .withGenericPrefabValues(Optional.class, Optional::of)
154
    .withGenericPrefabValues(Map.class, Map::of);
155

156
// Use across multiple classes
157
config.forClass(UserService.class).verify();
158
config.forClass(OrderService.class).verify();
159
config.forClass(ProductService.class).verify();
160
```
161

162
### Inheritance and Field Configuration
163

164
Configures how inheritance and field access are handled.
165

166
```java { .api }
167
/**
168
 * Signals that getClass is used in the implementation of the equals method,
169
 * instead of an instanceof check
170
 * @return this, for easy method chaining
171
 */
172
public ConfiguredEqualsVerifier usingGetClass();
173

174
/**
175
 * Determines how a getter name can be derived from a field name
176
 * @param converter A function that converts from field name to getter name
177
 * @return this, for easy method chaining
178
 */
179
public ConfiguredEqualsVerifier withFieldnameToGetterConverter(
180
    Function<String, String> converter
181
);
182

183
/**
184
 * Signals that all internal caches need to be reset
185
 * @return this, for easy method chaining
186
 * @deprecated No longer needed; this happens automatically
187
 */
188
@Deprecated
189
public ConfiguredEqualsVerifier withResetCaches();
190
```
191

192
**Usage Examples:**
193

194
```java
195
// Configure for getClass usage
196
ConfiguredEqualsVerifier config = EqualsVerifier.configure()
197
    .usingGetClass()
198
    .suppress(Warning.STRICT_INHERITANCE);
199

200
// Configure custom getter naming convention
201
ConfiguredEqualsVerifier config = EqualsVerifier.configure()
202
    .withFieldnameToGetterConverter(fieldName -> 
203
        "retrieve" + fieldName.substring(0, 1).toUpperCase() + fieldName.substring(1));
204
```
205

206
### Factory Methods for Class Verification
207

208
Creates verifiers for different types of class verification using the configuration.
209

210
```java { .api }
211
/**
212
 * Factory method for single class verification
213
 * @param type The class for which the equals method should be tested
214
 * @return A fluent API for EqualsVerifier
215
 */
216
public <T> SingleTypeEqualsVerifierApi<T> forClass(Class<T> type);
217

218
/**
219
 * Factory method for multiple class verification from iterable
220
 * @param classes An iterable containing the classes for which equals method should be tested
221
 * @return A fluent API for EqualsVerifier
222
 */
223
public MultipleTypeEqualsVerifierApi forClasses(Iterable<Class<?>> classes);
224

225
/**
226
 * Factory method for multiple class verification with varargs
227
 * @param first A class for which the equals method should be tested
228
 * @param second Another class for which the equals method should be tested
229
 * @param more More classes for which the equals method should be tested
230
 * @return A fluent API for EqualsVerifier
231
 */
232
public MultipleTypeEqualsVerifierApi forClasses(
233
    Class<?> first,
234
    Class<?> second,
235
    Class<?>... more
236
);
237

238
/**
239
 * Factory method for package scanning (non-recursive)
240
 * @param packageName A package for which each class's equals should be tested
241
 * @return A fluent API for EqualsVerifier
242
 */
243
public MultipleTypeEqualsVerifierApi forPackage(String packageName);
244

245
/**
246
 * Factory method for package scanning with recursion control
247
 * @param packageName A package for which each class's equals should be tested
248
 * @param scanRecursively true to scan all sub-packages
249
 * @return A fluent API for EqualsVerifier
250
 */
251
public MultipleTypeEqualsVerifierApi forPackage(
252
    String packageName, 
253
    boolean scanRecursively
254
);
255

256
/**
257
 * Factory method for package scanning with type filtering
258
 * @param packageName A package for which each class's equals should be tested
259
 * @param mustExtend if not null, returns only classes that extend or implement this class
260
 * @return A fluent API for EqualsVerifier
261
 */
262
public MultipleTypeEqualsVerifierApi forPackage(
263
    String packageName, 
264
    Class<?> mustExtend
265
);
266
```
267

268
**Usage Examples:**
269

270
```java
271
// Create shared configuration
272
ConfiguredEqualsVerifier config = EqualsVerifier.configure()
273
    .suppress(Warning.STRICT_INHERITANCE, Warning.NONFINAL_FIELDS)
274
    .withPrefabValues(ExternalDependency.class, redValue, blueValue);
275

276
// Apply to single classes
277
config.forClass(Person.class).verify();
278
config.forClass(Address.class).verify();
279

280
// Apply to multiple classes
281
config.forClasses(Person.class, Address.class, Phone.class).verify();
282

283
// Apply to packages
284
config.forPackage("com.example.model").verify();
285
config.forPackage("com.example.entities", true).verify();
286
```
287

288
### Advanced Configuration Patterns
289

290
**Hierarchical Configuration:**
291

292
```java
293
// Base configuration for all domain objects
294
ConfiguredEqualsVerifier baseDomainConfig = EqualsVerifier.configure()
295
    .suppress(Warning.STRICT_INHERITANCE)
296
    .withPrefabValues(CommonDependency.class, commonRed, commonBlue);
297

298
// Specialized configuration for JPA entities
299
ConfiguredEqualsVerifier jpaConfig = baseDomainConfig.copy()
300
    .suppress(Warning.SURROGATE_KEY, Warning.JPA_GETTER);
301

302
// Specialized configuration for DTOs
303
ConfiguredEqualsVerifier dtoConfig = baseDomainConfig.copy()
304
    .suppress(Warning.NONFINAL_FIELDS);
305

306
// Use specialized configurations
307
jpaConfig.forPackage("com.example.entities").verify();
308
dtoConfig.forPackage("com.example.dto").verify();
309
```
310

311
**Environment-Specific Configuration:**
312

313
```java
314
public class EqualsVerifierTestBase {
315
    protected static ConfiguredEqualsVerifier createConfig() {
316
        ConfiguredEqualsVerifier.Builder builder = EqualsVerifier.configure()
317
            .suppress(Warning.STRICT_INHERITANCE);
318
        
319
        if (isTestEnvironment()) {
320
            builder.withPrefabValues(DatabaseConnection.class, mockDb1, mockDb2);
321
        } else {
322
            builder.withPrefabValues(DatabaseConnection.class, realDb1, realDb2);
323
        }
324
        
325
        if (isLegacyMode()) {
326
            builder.suppress(Warning.STRICT_HASHCODE, Warning.NONFINAL_FIELDS);
327
        }
328
        
329
        return builder;
330
    }
331
}
332

333
// Usage in test classes
334
ConfiguredEqualsVerifier config = createConfig();
335
config.forClass(UserEntity.class).verify();
336
```
337

338
**Factory Configuration for Testing Frameworks:**
339

340
```java
341
// JUnit 5 extension for shared configuration
342
@ExtendWith(EqualsVerifierExtension.class)
343
class PersonTest {
344
    @EqualsVerifierConfig
345
    static ConfiguredEqualsVerifier config() {
346
        return EqualsVerifier.configure()
347
            .suppress(Warning.STRICT_INHERITANCE)
348
            .withPrefabValues(Address.class, 
349
                new Address("123 Main St"), 
350
                new Address("456 Oak Ave"));
351
    }
352
    
353
    @Test
354
    void testPersonEquals() {
355
        config().forClass(Person.class).verify();
356
    }
357
}
358
```
359

360
**Configuration Composition:**
361

362
```java
363
// Compose configurations for different layers
364
public static class Configurations {
365
    public static final ConfiguredEqualsVerifier ENTITY_CONFIG = 
366
        EqualsVerifier.configure()
367
            .suppress(Warning.SURROGATE_KEY, Warning.JPA_GETTER);
368
    
369
    public static final ConfiguredEqualsVerifier DTO_CONFIG = 
370
        EqualsVerifier.configure()
371
            .suppress(Warning.NONFINAL_FIELDS);
372
    
373
    public static final ConfiguredEqualsVerifier VALUE_OBJECT_CONFIG = 
374
        EqualsVerifier.simple();
375
    
376
    public static ConfiguredEqualsVerifier withCommonPrefabs(
377
            ConfiguredEqualsVerifier base) {
378
        return base.copy()
379
            .withPrefabValues(UUID.class, UUID.randomUUID(), UUID.randomUUID())
380
            .withGenericPrefabValues(Optional.class, Optional::of);
381
    }
382
}
383

384
// Usage
385
Configurations.withCommonPrefabs(Configurations.ENTITY_CONFIG)
386
    .forPackage("com.example.entities")
387
    .verify();
388
```