AssertJ assertions generator maven plugin

This maven plugin generates AssertJ assertions specific to your own classes, it's a wrapper of the AssertJ Assertions Generator.

Starting with version 2.0, users can now customize generated assertions by using their own templates.

Big thanks to Michal Ostruszka for his major contributions to this plugin.

You need to configure your project pom.xml in order to use the maven assertions generator plugin.

<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <!-- use version 2.1.0 or higher -->
    <version>2.1.0</version>
    <scope>test</scope>
</dependency>

To generate custom assertions, add the following plugin to your pom.xml :

<plugin>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-assertions-generator-maven-plugin</artifactId>
    <version>2.1.0</version>
    <configuration>
        <packages>
            <param>your.first.package</param>
            <param>your.second.package</param>
        </packages>
        <classes>
            <param>your.third.package.YourClass</param>
        </classes>
    </configuration>
</plugin>

Execute the command :

mvn assertj:generate-assertions

By default, assertions are generated in the target/generated-test-sources/assertj-assertions/ folder.

Execution example in assertj-examples project :

====================================
AssertJ assertions generation report
====================================

--- Generator input parameters ---

The following templates will replace the ones provided by AssertJ when generating AssertJ assertions :
- Using custom template for 'object assertions' loaded from ./templates/my_has_assertion_template.txt
- Using custom template for 'hierarchical concrete class assertions' loaded from ./templates/my_assertion_class_template.txt

Generating AssertJ assertions for classes in following packages and subpackages:
- org.assertj.examples.data

Input classes excluded from assertions generation:
- org.assertj.examples.data.MyAssert

--- Generator results ---

Directory where custom assertions files have been generated :
- /assertj/assertj-examples/assertions-examples/target/generated-test-sources/assertj-assertions

# full path truncated for to improve clarity in the website.
Custom assertions files generated :
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/AlignmentAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/BasketBallPlayerAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/BookAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/BookTitleAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/EmployeeAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/EmployeeTitleAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/MagicalAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/MansionAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/NameAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/PersonAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/RaceAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/RingAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/TeamAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/TolkienCharacterAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/movie/MovieAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/neo4j/DragonBallGraphAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/service/GameServiceAssert.java
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/service/TeamManagerAssert.java

No custom assertions files generated for the following input classes as they were not found:
- com.fake.UnknownClass1
- com.fake.UnknownClass2

Assertions entry point class has been generated in file:
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/Assertions.java

Soft Assertions entry point class has been generated in file:
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/SoftAssertions.java

JUnitSoftAssertions entry point class has been generated in file:
- .../generated-test-sources/assertj-assertions/org/assertj/JUnitSoftAssertions.java

BDD Assertions entry point class has been generated in file:
- .../generated-test-sources/assertj-assertions/org/assertj/examples/data/BddAssertions.java

Let's start with an example, the description of each configuration element is done afterwards :

<plugin>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-assertions-generator-maven-plugin</artifactId>
  <version>2.1.0</version>
  
  <!-- Generate assertions at every build -->
  <executions>
    <execution>
      <goals>
        <goal>generate-assertions</goal>
      </goals>
    </execution>
  </executions>

  <configuration>

    <!-- List the package of classes you want to generate assertions for -->
    <packages>
      <param>org.assertj.examples.rpg</param>
      <param>org.assertj.examples.data</param>
      <param>com.google.common.net</param>
    </packages>

    <!-- List the classes you want to generate assertions for -->
    <classes>
      <param>java.nio.file.Path</param>
      <param>com.fake.UnknownClass</param>
    </classes>

    <!-- Whether generated assertions classes can be inherited with consistent assertion chaining -->
    <hierarchical>true</hierarchical>

    <!-- 
      If true, generate assertions for all fields whatever their visibility is (including private).
      Default to false which means assertions are only generated for public fields.
    -->
    <generateAssertionsForAllFields>true</generateAssertionsForAllFields>
    
    <!-- Where to generate assertions entry point classes -->
    <entryPointClassPackage>org.assertj</entryPointClassPackage>

    <!-- Restrict classes to generate assertions for with regex -->
    <includes> 
      <param>org\.assertj\.examples\.rpg.*</param> 
    </includes>

    <!-- Exclude classes matching the regex from generation -->
    <excludes>
      <param>.*google.*HostSpecifier</param>
      <param>.*google.*Headers</param>
      <param>.*google.*MediaType</param>
      <param>.*google.*Escaper.*</param>
      <param>.*Examples.*</param>
    </excludes>

    <!-- Sets the base directory where to generate assertions -->
    <targetDir>src/test/generated-assertions</targetDir>
    
    <!-- If true, all files in targetDir are removed before generating new ones (default to false) -->
    <cleanTargetDir>true</cleanTargetDir>

    <!-- 
      Set the package where assertion classes are generated, combine it with targetDir to
      get the path to assertions classes.       
      Ex: com.nba.Player -> src/test/generated-assertions/my/assertions/PlayerAssert 

      If not set, each assertion class is generated in the package of the class to assert.
      Ex: com.nba.Player -> src/test/generated-assertions/com/nba/PlayerAssert 
    -->
    <generateAssertionsInPackage>my.assertions</generateAssertionsInPackage>

    <!-- Select which assertions entry point classes to generate -->
    <generateAssertions>true</generateAssertions>
    <generateBddAssertions>true</generateBddAssertions>
    <generateSoftAssertions>true</generateSoftAssertions>
    <generateJUnitSoftAssertions>true</generateJUnitSoftAssertions>

    <!-- 
      Set the scope of generated sources when added to the maven build.
      Value must be 'test' or 'compile' to and defaults to 'test'.
    -->
    <generatedSourcesScope>compile</generatedSourcesScope>

    <!-- If true, the plugin does not produce any logs (default to false) -->
    <quiet>true</quiet>

    <!-- 
      The generated assertions report is written to the given file.
      The base directory containing the report file is where the plugin is executed. 
    -->
    <writeReportInFile>assertions-generation-report.txt</writeReportInFile>

    <!-- If true, do not generate assertions, it's a way to disable the plugin -->
    <skip>true</skip>

  </configuration>
</plugin>
packages and classes configuration elements indicate where to find the classes you want to generate assertions for.

Instead of declaring packages / classes in the pom.xml you can use the properties assertj.packages and assertj.classes:

mvn assertj:generate-assertions -Dassertj.packages=your.first.package,your.second.package

Sometimes - not to say often - you don't want to generate assertions for all the classes of the specified packages. To avoid that, exclude classes using regular expressions. In the example below, we generate assertions for all classes in com.google.common.net except for classes finishing with HostSpecifier, Headers or containing Escaper :

<configuration>
    <packages>
        <param>com.google.common.net</param>
    </packages>
    <excludes>
        <param>.*google.*HostSpecifier</param>
        <param>.*google.*Headers</param>
        <param>.*google.*Escaper.*</param>
    </excludes>
</configuration>

From the specified packages, it might be easier to restrict the classes you want to generate assertions for. You can do this by including them using regular expressions. Only classes from the specified packages matching at least one of the given regular expressions will have assertions generated for. In the example below, assertions will only be generated for DTO and Model classes :

<configuration>
    <packages>
        <param>com.my.project</param>
    </packages>
    <includes>
        <param>.*DTO</param>
        <param>.*Model</param>
    </includes>
</configuration>

You can specify the directory where assertion files are generated using the targetDir configuration element, e.g. :

<configuration>
    <packages>
        <param>your.first.package</param>
        <param>your.second.package</param>
    </packages>
    <targetDir>src/test/java</targetDir>
</configuration>

By default all assertions entry point classes are generated (JUnitSoftAssertions are not generated if JUnit can not be found). You can configure which entry point classes to generate as shown below :

<configuration>
        <packages>
            <param>your.first.package</param>
            <param>your.second.package</param>
        </packages>
        <!-- select entry point classes to generate -->
        <generateAssertions>false</generateAssertions>
        <generateBddAssertions>true</generateBddAssertions>
        <generateSoftAssertions>true</generateSoftAssertions>
        <generateJUnitSoftAssertions>true</generateJUnitSoftAssertions>
    </configuration>
</plugin>

Assertions entry point classes are generated in a package determined programatically, you can change it with the entryPointClassPackage configuration property :

<configuration>
    <entryPointClassPackage>my.entry.point.package</entryPointClassPackage>
</configuration>

You can generate assertion classes that don't hide subclasses assertions after using an assertion from a super class. To do that, we need to generate two classes per domain class, e.g. for the Book domain class, AbstractBookAssert.java and BookAssert.java will be generated. Set the hierarchical property to true to enable this :

<configuration>
    <hierarchical>true</hierarchical>
</configuration>

Assertions are generated using templates that define skeleton code with variables, as explained in detail here.

Since version 2.0, users can replace the existing templates by their own to change how assertions are generated. See below an example of such a configuration :

<configuration>
    <templates>
        <!-- specify the base directory where to look for templates -->
        <templatesDirectory>src/test/resources/templates/</templatesDirectory>
        <!-- change Object generated assertions (ex hasName(String expected)) -->
        <objectAssertion>my_object_assertion_template.txt</objectAssertion>
        <!-- change Iterable generated assertions (ex hasTeamMates(String... teamMates)) -->
        <iterableAssertion>my_iterable_assertion_template.txt</iterableAssertion>
    </templates>
</configuration>
Configurable template properties :
<templates>

  <!-- assertion method templates -->     
  <objectAssertion>my_has_assert_template.txt</objectAssertion>
  <arrayAssertion>my_array_assert_template.txt</arrayAssertion>
  <iterableAssertion>my_iterable_assert_template.txt</iterableAssertion>
  <booleanAssertion>my_boolean_assert_template.txt</booleanAssertion>
  <booleanWrapperAssertion>my_Boolean_wrapper_assert_template.txt</booleanWrapperAssertion>
  <charAssertion>my_char_assert_template.txt</charAssertion>
  <characterAssertion>my_Character_assert_template.txt</characterAssertion>
  <realNumberAssertion>my_real_number_assert_template.txt</realNumberAssertion>
  <realNumberWrapperAssertion>my_real_number_wrapper_assert_template.txt</realNumberWrapperAssertion>
  <wholeNumberAssertion>my_whole_number_assert_template.txt</wholeNumberAssertion>
  <wholeNumberWrapperAssertion>my_whole_number_wrapper_assert_template.txt</wholeNumberWrapperAssertion>

  <!-- assertion class templates -->
  <assertionClass>my_assertion_class_template.txt<assertionClass>
  <hierarchicalAssertionConcreteClass>my_hierarch_concrete_class.txt</hierarchicalAssertionConcreteClass>
  <hierarchicalAssertionAbstractClass>my_hierarch_base_class.txt</hierarchicalAssertionAbstractClass>

  <!-- entry point templates -->
  <assertionsEntryPointClass>my_Assertions_class_template.txt</assertionsEntryPointClass>
  <assertionEntryPointMethod>my_assertThat_method_template.txt</assertionEntryPointMethod>
  <bddEntryPointAssertionClass>my_BddAssertions_class_template.txt</bddEntryPointAssertionClass>
  <bddEntryPointAssertionMethod>my_then_method_template.txt</bddEntryPointAssertionMethod>/
  <softEntryPointAssertionClass>my_SoftAssertions_class_template.txt</softEntryPointAssertionClass>
  <softEntryPointAssertionMethod>my_soft_assertThat_method_template.txt</softEntryPointAssertionMethod>
  <junitSoftEntryPointAssertionClass>my_JunitSoftAssertions_class_template.txt</junitSoftEntryPointAssertionClass>

</templates>
Default template properties values (used if not replaced) :
Assertion method property Default template file
objectAssertion has_assertion_template.txt
arrayAssertion has_elements_assertion_template_for_array.txt
iterableAssertion has_elements_assertion_template_for_iterable.txt
booleanAssertion is_assertion_template.txt
booleanWrapperAssertion is_wrapper_assertion_template.txt
charAssertion has_assertion_template_for_char.txt
characterAssertion has_assertion_template_for_character.txt
wholeNumberAssertion has_assertion_template_for_whole_number.txt
wholeNumberWrapperAssertion has_assertion_template_for_whole_number_wrapper.txt
realNumberAssertion has_assertion_template_for_real_number.txt
realNumberWrapperAssertion has_assertion_template_for_real_number_wrapper.txt

Assertion class property Default template file
assertionClass custom_assertion_class_template.txt
hierarchicalAssertionAbstractClass custom_abstract_assertion_class_template.txt
hierarchicalAssertionConcreteClass custom_hierarchical_assertion_class_template.txt

Assertion entry point property Default template file
assertionsEntryPointClass standard_assertions_entry_point_class_template.txt
assertionEntryPointMethod standard_assertion_entry_point_method_template.txt
bddEntryPointAssertionClass bdd_assertions_entry_point_class_template.txt
bddEntryPointAssertionMethod bdd_assertion_entry_point_method_template.txt
softEntryPointAssertionClass soft_assertions_entry_point_class_template.txt
softEntryPointAssertionMethod soft_assertion_entry_point_method_template.txt
junitSoftEntryPointAssertionClass junit_soft_assertions_entry_point_class_template.txt
Where can default template files be found ?

The default template files can be found either in the assertj-assertions-generator-2.x.x jar or in assertj-assertions-generator github project.

To generate assertions classes with every build, add an <executions> section as shown below :

<plugin>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-assertions-generator-maven-plugin</artifactId>
    <version>2.1.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate-assertions</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <packages>
            <param>your.first.package</param>
            <param>your.second.package</param>
        </packages>
    </configuration>
</plugin>

To disable assertions generation, set assertj.skip to true:

mvn assertj:generate-assertions -Dassertj.skip=true

Release date : 2017-10-01

  • Uses assertj-assertions-generator 2.1.0.
  • Breaking change: Generates hierarchical assertions by default (set hierarchical to false to keep the old behaviour).
  • Add cleanTargetDir flag to clean the directory where assertions are generated before generating new ones.
  • Add quiet flag to quiet the plugin (no output logs).
  • Add writeReportInFile option to write plugin output to the given file.
  • Add generatedSourcesScope option to set the scope of generated sources (defaults to test).
  • Add generateAssertionsForAllFields flag to generate assertions for all fields whatever their visibility is.
  • Add generateAssertionsInPackage to specify in which package assertions are generated (if not set, assertions are generated in the same package as the class to assert).
For all new configuration elements, see the plugin configuration example.

Release date : 2015-08-16

Release date : 2015-04-11

Release date : 2014-11-02

  • Uses assertj-assertions-generator 1.5.0 which adds JUnitSoftAssertions generation.
  • Allow to select which assertions entry point classes are generated among Assertions, BddAssertions,SoftAssertions and JUnitSoftAssertions.
  • Assertions generation report list the input classes that were not found.

Release date : 2014-08-31

Release date : 2014-08-17

Release date : 2014-08-04

  • Uses assertj-assertions-generator 1.3.0 with :
    • Better generated assertions for double and float types using offset.
    • Generated assertions for public fields.
    • Avoid potential inner class assertion name clash when several inner classes have the same name.
  • Allow to generate assertion classes that don't hide subclasses assertions after using an assertion from a super class. (Fr Jeremy Krieg)
  • Allow to specify where to generate Assertions entry point classes.
  • Generate a BDD style entry point class BddAssertions replacing assertThat methods by then.
  • Generate a SoftAssertions entry point class to collect all assertion errors instead of stopping at the first one.
  • Better generation report.

Release date : 2013-12-08

Special thanks to Jean Christophe Gay for its contributions to this version.

  • Uses assertj-assertions-generator 1.2.0.
  • To ease using generated assertions, generate an entry point class Assertions providing assertThat methods giving access to each generated *Assert classes.
  • Better logs to understand what the plugin is doing.
  • Define property for each parameter: classes, packages and targetDir. (Jean Christophe Gay)
  • Generate Help Mojo accessible via command mvn assertj:help. (Jean Christophe Gay)
  • Define property for each parameter: classes, packages and targetDir. (Jean Christophe Gay)
  • Use up to date @parameter syntax to fix warning logs. (Jean Christophe Gay)

Release date : 2013-09-15

This version uses assertj-assertions-generator 1.1.0.

Release date : 2013-03-26

The first release after Fest fork, generated assertions are cleaner.

If you have any questions, please use AssertJ google group.

AssertJ assertions generator maven plugin is hosted on github : https://github.com/joel-costigliola/assertj-assertions-generator-maven-plugin.

Please report bugs or missing features in AssertJ assertions generator maven plugin issue tracker.

Thanks for your interest ! Please check our contributor's guidelines.

Special thanks to AssertJ assertions generator maven plugin contributors:

  • Jean Christophe Gay
  • Michal Ostruszka