AssertJ Generator Gradle Plugin

This is the source for the Gradle plugin for the AssertJ Generator. This plugin leverages existing Gradle SourceSet API to make it easier to integrate the AssertJ Generator into existing Gradle-based projects. The configurations available mimic those provided by the AssertJ Generator Maven Plugin.

This plugin will automatically detect Kotlin, and Java sources. The plugin automatically configures the generation step for each SourceSet (except test) in a Gradle project when applied.

Quick Start

Below is a minimal configuration that will cause all classes defined in the main source set to have an assertJ assertion generated for it. All of these will be placed into the longest common package of the sources presented.

This plugin is built with Gradle 7.6.

plugins {
  id 'org.assertj.generator' version '1.1.0'
}

// add some classpath dependencies
repositories {
  mavenCentral()
}

dependencies {
  testCompile group: 'org.assertj', name: 'assertj-core', version: '3.24.2'
  testCompile group: 'junit', name: 'junit', version: '4.12'
}

License

This plugin is licensed under the Apache License.

Configuration

Primary configuration of included/excluded files is done via the same mechanisms that are used for Gradle's SourceSet DSL. For explanation on how filters work, please review the Java Plugin Tutorial for Gradle. This plugin utilizes the filters to gather classes to run against the generator.

Parameters

The following sections outline the available parameters, linking to the appropriate generator docs when available.

For any unlisted parameters, please see the javadoc for AssertJGeneratorExtension and open issues for unclear/missing documentation.

skip - boolean

Default: false

The skip parameter provides a mechanism for quickly turning on/off assertJ generation. Unless overridden in the global scope, no code will be generated by default. When an assertJ block is defined in a local scope, this parameter is set to false for the source set.

Example

The following example turns off generation for main. All classes found within main will be ignored.

sourceSets {
  main {
      assertJ { skip = true } // sets skip = true
  }
}

If debugging a build, it may be useful to turn off generation for a sourceSet. To do this, inside the configuration block, set skip = true.

sourceSets {
  brokenGeneration {
    assertJ {
      skip = true // no assertions will be generated for "brokenGeneration"
    }
  }
}

outputDir - File

Default: ${buildDir}/generated-srcs/${sourceSet.name}-test/java

The root directory where all generated files will be placed (within sub-folders for packages).

Changing this parameter will place all generated files into the passed directory. Any relative path specified is relative to the build directory as any sources should not be checked into source control and destroyed with clean. However, in true Gradle tradition, this may use any absolute path.

The following example changes the output directory for the main SourceSet to be ${buildDir}/src-gen/main-test/java.

sourceSets {
  main {
    assertJ {
      // default: ${buildDir}/generated-srcs/${sourceSet.name}-test/java
      outputDir = file("src-gen/main-test/java")
    }
  }
}

templates - Templates

Default: Built-in templates

Templates can be configured to change the output of the generator. The templates to be replaced can be specified via either Strings or Files.

For more information on template syntax, please see the AssertJ Generator Templates Section.

The names of templates mirror those from the AssertJ Documentation, but the actual names and nesting are listed here.

The following example replaces the whole number field with a custom template for only the main sourceSet, any others remain unaffected.

sourceSets {
  main {
    assertJ {
      templates {
        methods {
          wholeNumberPrimitive.template('public get${Property}() { }')
        }
      }
    }
  }
}

The following example changes the template to a file() template for the main source sets. The file() method accepts any parameter allowed by Project#file(...).

sourceSets {
  main {
    assertJ {
      templates {
        // Set the template to file content: ./wholeNumberOverride.txt
        methods {
          wholeNumberPrimitive.file('wholeNumberOverride.txt')
        }
      }
    }
  }
}

packages - JavaPackageNamePatternFilterable

Default: All packages

Package filters can be used to include, or exclude individual or groups of packages to be generated. These filters use a similar pattern to include/exclude with SourceSet.

sourceSets {
  main {
    assertJ {
      packages {
        include "org.example**" // include *all* packages in `org.example`
        exclude "org.example.foo" // exclude `org.example.foo` specifically
     }
    }
  }
}

See PackageFilter tests for more examples.

classes - JavaClassPatternFilterable

Default: All classes

Class filters can be used to include, or exclude individual patterns of fully-qualified class names to be generated. These filters use a similar pattern to include/exclude with SourceSet.

sourceSets {
  main {
    assertJ {
      classes {
        include "org.example.**" // include *all* classes under `org.example` including sub-packages
        exclude "org.example.Foo" // exclude class `org.example.Foo` specifically
      }
    }
  }
}

See ClassesFilter tests for more examples.

entryPoints - EntryPointsGeneratorOptions

Default: Only generate "standard" assertion entrypoint

Entry points are classes that provide mechanisms to get access to all of the generated AssertJ types. The AssertJ Generator - Entry Points explains how these work and what is expected to be generated for each entry point. The following table shows a mapping value to entry point:

Value	Enum Value	Entry Point
bdd	BDD	BDD style
standard	STANDARD	Standard assertions style
junitSoft	JUNIT_SOFT	JUnit Soft
soft	SOFT	Soft

(This table is likely incomplete, please see the AssertJ Generator Docs)

By default, only the standard style is turned on. To adjust this, simply set the values to true within the entryPoints closure.

sourceSets {
  main {
    assertJ {
      entryPoints {
        standard = false // No more standard generation
        bdd = true       // Turn on BDD
        junitSoft = true // and JUnit Soft
      }
    }
  }
}

A useful trick to turn on only a set of values is to just set the entryPoints to a collection of types:

sourceSets {
  main {
    assertJ {
      entryPoints = ['BDD', 'JUNIT_SOFT'] // turn on _only_ BDD and JUnit Soft
    }
  }
}

Or within the entryPoints closure:

sourceSets {
  main {
    assertJ {
      entryPoints {
        only 'BDD', 'JUNIT_SOFT' // turn on _only_ BDD and JUnit Soft
      }
    }
  }
}

Task Provided

• generateAssertJ - Generates all sources via the AssertJ Generator
• Cleaning is done via the clean as the input/output semantics are handled by Gradle's incremental compilation mechanics

Lifecycle

This plugin injects itself where it is needed for complete compilation.

1. Java code that will be "generated from" is compiled
2. These compiled classes and the source files "classpath" are used to generate the files
3. These files are placed into the source compilation path for the SourceSet's compileJava task

Alternatives

There exists several other alternative Gradle plugins that perform the same functionality as this one. Currently, known:

• opengl-8080/assertjGen-gradle-plugin - built to wrap the example provided by @joel-costigiola, here which does not allow for configuration. This plugin does not tie the plugin to a specific version of the AssertJ Generator
• fhermansson/assertj-generator-gradle-plugin - only works on a single source-set and still just wraps package/class names as strings