https://github.com/assertj/assertj-generator-gradle-plugin
Gradle plugin for the AssertJ Generator
https://github.com/assertj/assertj-generator-gradle-plugin
Last synced: 9 months ago
JSON representation
Gradle plugin for the AssertJ Generator
- Host: GitHub
- URL: https://github.com/assertj/assertj-generator-gradle-plugin
- Owner: assertj
- License: apache-2.0
- Created: 2017-05-30T09:22:04.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2025-04-14T21:50:19.000Z (9 months ago)
- Last Synced: 2025-04-15T02:17:12.195Z (9 months ago)
- Language: Kotlin
- Homepage:
- Size: 380 KB
- Stars: 32
- Watchers: 3
- Forks: 5
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AssertJ Generator Gradle Plugin
[](https://plugins.gradle.org/plugin/org.assertj.generator)
[](./LICENSE)
This is the source for the Gradle plugin for the
[AssertJ Generator](http://joel-costigliola.github.io/assertj/assertj-assertions-generator.html). This plugin leverages
existing Gradle [SourceSet](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.SourceSet.html) 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](http://joel-costigliola.github.io/assertj/assertj-assertions-generator-maven-plugin.html).
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.
```groovy
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](./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](https://docs.gradle.org/current/userguide/java_plugin.html#sec:changing_java_project_layout).
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`](./src/main/kotlin/org/assertj/generator/gradle/tasks/config/AssertJGeneratorExtension.kt)
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.
```groovy
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`.
```groovy
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`.
```groovy
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 `String`s or `File`s.
For more information on template syntax, please see the
[AssertJ Generator Templates Section](http://joel-costigliola.github.io/assertj/assertj-assertions-generator.html#generated-assertions-templates).
The names of templates mirror those from the AssertJ Documentation, but the actual names and nesting are listed
[here](src/main/kotlin/org/assertj/generator/gradle/tasks/config/Templates.kt).
The following example replaces the whole number field with a custom template for only the `main` sourceSet, any others
remain unaffected.
```groovy
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(...)`](https://docs.gradle.org/7.6.1/dsl/org.gradle.api.Project.html#org.gradle.api.Project:file(java.lang.Object)).
```groovy
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`.
```groovy
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](src/test/kotlin/org/assertj/generator/gradle/parameter/PackageFilter.kt) 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`.
```groovy
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](src/test/kotlin/org/assertj/generator/gradle/parameter/ClassesFilter.kt) 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](http://joel-costigliola.github.io/assertj/assertj-assertions-generator.html#generated-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](http://joel-costigliola.github.io/assertj/assertj-core-news.html#assertj-core-1.6.0-bdd-assertions-style) |
| `standard` | `STANDARD` | [Standard assertions style](http://joel-costigliola.github.io/assertj/assertj-assertions-generator.html#generated-entry-points) |
| `junitSoft` | `JUNIT_SOFT` | [JUnit Soft](http://joel-costigliola.github.io/assertj/assertj-core-features-highlight.html#soft-assertions) |
| `soft` | `SOFT` | [Soft](http://joel-costigliola.github.io/assertj/assertj-core-features-highlight.html#soft-assertions) |
(This table is likely incomplete, please see
the [AssertJ Generator Docs](http://joel-costigliola.github.io/assertj/assertj-assertions-generator.html#generated-entry-points))
By default, only the `standard` style is turned on. To adjust this, simply set the values to `true` within the
`entryPoints` closure.
```groovy
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:
```groovy
sourceSets {
main {
assertJ {
entryPoints = ['BDD', 'JUNIT_SOFT'] // turn on _only_ BDD and JUnit Soft
}
}
}
```
Or within the `entryPoints` closure:
```groovy
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](https://github.com/opengl-8080/assertjGen-gradle-plugin) - built to wrap the
example provided by
@joel-costigiola, [here](https://github.com/joel-costigliola/assertj-assertions-generator/blob/master/src/main/scripts/build.gradle)
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](https://github.com/fhermansson/assertj-generator-gradle-plugin) - only
works on a single source-set and still just wraps package/class names as strings