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.0.0 or higher -->
    <version>2.0.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.0.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.0.0</version>
  
  <!-- generate assertions at every build -->
  <executions>
    <execution>
      <goals>
        <goal>generate-assertions</goal>
      </goals>
    </execution>
  </executions>

  <configuration>

    <!-- list the package whose 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>

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

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

    <!-- base directory where to generate assertions -->
    <targetDir>src/test/generated-assertions</targetDir>

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

  </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>
        <excludes>
            <param>.*google.*HostSpecifier</param>
            <param>.*google.*Headers</param>
            <param>.*google.*Escaper.*</param>
        </excludes>
    </packages>
</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>
        <includes>
            <param>.*DTO</param>
            <param>.*Model</param>
        </includes>
    </packages>
</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.0.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.0.0 release

Release date : 2015-08-16

Release notes:

Assertions generator maven plugin 1.6.0 release

Release date : 2015-04-11

Release notes:

Assertions generator maven plugin 1.5.0 release

Release date : 2014-11-02

Release notes:
  • 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

Release notes:

Assertions generator maven plugin 1.4.0 release

Release date : 2014-08-17

Release notes:

Assertions generator maven plugin 1.3.0 release

Release date : 2014-08-04

Release notes:
  • 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.

Release notes:
  • 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