matcher-generator v5.1.0

This chapter takes you from an empty Maven build to a first green test. The examples are Java. The Kotlin chapter covers the KAPT setup of Kotlin projects.

Requirements

  • Java 17 or newer. Since 6.0.0 the generated code needs Java 17; users who stay on Java 11 stay on 5.x.

  • A test dependency on Hamcrest for the Hamcrest backend, or on AssertJ for the AssertJ backend. The examples use Hamcrest 3.0 and AssertJ 3.27.7. You can use both backends in one project.

Dependencies

Add the generator for your backend. It is the annotation processor, so the matchers are generated while your sources compile. The snippet reads the version from a property, hamcrest-matcher-generator.version, which you define once in your build as the release you use, currently 5.1.0:

<dependency>
    <groupId>io.github.marmer.testutils</groupId>
    <artifactId>hamcrest-matcher-generator</artifactId>
    <version>${hamcrest-matcher-generator.version}</version>
</dependency>
<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>hamcrest</artifactId>
</dependency>

Declare the processor on the processor path of the compiler plugin, as the example does, so that the build finds it without relying on the classpath:

<annotationProcessorPaths combine.children="append">
    <path>
        <groupId>io.github.marmer.testutils</groupId>
        <artifactId>hamcrest-matcher-generator</artifactId>
        <version>${hamcrest-matcher-generator.version}</version>
    </path>
</annotationProcessorPaths>

The scope of the generator decides where the generated code can be compiled. The examples declare it with the test scope, because the matchers are generated for test code. When the configuration sits in your production sources, the generated code is compiled with production code too, so the generator must be on the compile classpath of production code: declare it with the provided scope and <optional>true</optional> then, so that it does not travel with your production artifact.

For AssertJ, use the assertj-assertion-generator artifact with the same two steps and the property assertj-assertion-generator.version. The AssertJ backend chapter shows its snippets from example-maven-java-assertj.

Configure the types

The processor generates for the types you configure. Put one annotation on a class of your choice and name the packages or classes of your model:

import io.github.marmer.matchergenerator.annotations.GenerateMatchers;

/** Generates a matcher for every model class in {@code example.hamcrest.model}. */
@GenerateMatchers("example.hamcrest.model")
public final class HamcrestConfiguration {}

The configuration chapter lists the options.

A first test

With the configuration above, the processor generates CustomerMatcher for the Customer class in example.hamcrest.model. A basic assertion checks one property by equality:

assertThat(ADA, isCustomer().withName("Ada"));

Generated code

The processor writes the matchers and assertions as source files, and your build compiles them like code you wrote. The generated files carry @Generated and no license header.

The generated code belongs to you. It is not covered by the project’s Apache License 2.0, so you can use it, change it and ship it in your own projects.

Next steps