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.

Quickstart

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

1 - Add AssertJ Core dependency to your pom.xml

<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>

2 - Configure the plugin in the build/plugins section of your pom.xml

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>

3 - Launch the maven 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

Plugin configuration

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>

 Specify packages and classes

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

 Including and excluding classes from assertion generation

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>

 Generated classes destination directory

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>

 Selecting which assertion entry point classes to generate

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 directory

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>

 Generating hierarchical assertion classes

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>

 Customizing generated assertions

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.

 Generating assertion classes with every build

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>

 Disabling assertions generation

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

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

Assertions generator maven plugin 2.1.0 release

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.

Assertions generator maven plugin 2.0.0 release

Release date : 2015-08-16

• Uses assertj-assertions-generator 2.0.0.
• Allow users to customize generated assertions using their own templates.
• Documentation improvements.

Assertions generator maven plugin 1.6.0 release

Release date : 2015-04-11

• Uses assertj-assertions-generator 1.6.0.

Assertions generator maven plugin 1.5.0 release

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.

Assertions generator maven plugin 1.4.1 release

Release date : 2014-08-31

• Uses assertj-assertions-generator 1.4.0 which fixes a bunch of issues.

Assertions generator maven plugin 1.4.0 release

Release date : 2014-08-17

• Uses assertj-assertions-generator 1.3.1
• Allow to generate assertion for classes located in src/test/java
• Allow to generate assertion for classes located in project dependencies
• Allow selecting classes to generate assertions for with regexp (see Configuration).
• Add skip option (see Configuration).

Assertions generator maven plugin 1.3.0 release

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.

Assertions generator maven plugin 1.2.0 release

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)

Assertions generator maven plugin 1.1.0 release

Release date : 2013-09-15

This version uses assertj-assertions-generator 1.1.0.

Assertions generator maven plugin 1.0.0 release

Release date : 2013-03-26

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

Mailing list

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

Code and issue tracker

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.

Contributing

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

Special thanks to AssertJ assertions generator maven plugin contributors:

• Jean Christophe Gay
• Michal Ostruszka