Code quality & testing
A healthy codebase runs more than a compiler over its sources. Jenesis wires in the usual quality tools
(static analysis, formatters, coverage, profiling, mutation testing) and a faster inner test loop. Each tool
turns itself on when a configuration folder holds its file, and stays off when none does. A tool the build
downloads is an official plugin, which the build resolves by itself wherever it finds that file: no line of
jenesis. names it. This chapter is the set of tools and how each one behaves.
Every file below lives in a configuration folder (build. by default). Configuration covers
where those folders sit and how per-module and profile overrides work; here we only care about which file
switches on which tool.
Static analysis
Each linter is switched on by a properties file named after it, such as checkstyle.. The file names
the tool's own configuration as configuration=, resolved against the folder of the properties file, and
the build hands that file to the tool under the name the tool reads, whatever it is called. The other lines of
the file are the plugin's values:
# build.jenesis/checkstyle.properties
configuration=checkstyle.xml
checkstyle.severity=warning
Where no configuration folder holds the properties, the tool's own file under its conventional name switches
the tool on alone and is handed to it as it stands, as a pmd. in build. runs PMD. A file at the
project root never switches a tool on.
| Properties file | Or, alone | Tool | Inspects |
|---|---|---|---|
checkstyle. |
checkstyle. |
Checkstyle | Java sources |
pmd. |
pmd. |
PMD | Java sources |
detekt. |
detekt. |
detekt | Kotlin sources |
ktlint. |
. |
ktlint | Kotlin sources |
scalastyle. |
scalastyle-config. |
Scalastyle | Scala sources |
scalafmt. |
. |
scalafmt, as a check | Scala sources |
codenarc. |
codenarc. |
CodeNarc | Groovy sources |
spotbugs. |
spotbugs-exclude. |
SpotBugs | compiled classes |
forbiddenapis. |
forbiddenapis | compiled classes | |
jdeps. |
the JDK's jdeps | compiled classes | |
jdeprscan. |
the JDK's jdeprscan | compiled classes |
Where a configuration folder holds the properties, the conventional file is never read in their place.
Properties that leave out configuration fail the build, naming the key to add:
.../build.jenesis/checkstyle.properties names no configuration - add configuration=checkstyle.xml, the file relative to checkstyle.properties
A configuration naming a file that does not exist fails the build as well. SpotBugs runs without a filter, so
a spotbugs. may leave configuration out and report every finding.
Every check runs in its module's verify phase, once the module is built: the modules that depend on it build
and run their tests without waiting for its checks, and a failed check still fails the build. Each downloaded
tool resolves in the tool group of its plugin, such as checkstyle:tool, kept apart from your project's own
dependencies, floats a RELEASE version until pinned, and runs in a JVM of its own. A tool whose language is
not present skips itself: detekt in a pure-Java project does nothing.
Reporting or failing on findings
A linter reports by default: it runs and records its findings, but never fails the build. That makes it safe to turn a tool on across an existing codebase without an immediate red build. A linter that found something says so in one line, with the number of findings and where its report is:
[FINDINGS] checkstyle found 2 findings, reported in target/build/.../reports/checkstyle/checkstyle-report.xml
-Djenesis. leaves that line out. To fail the build on a linter's findings, set its
jenesis. to true, on the command line or in jenesis., as
-Djenesis.. The setting exists for checkstyle, pmd, detekt, ktlint,
scalastyle, scalafmt, codenarc, spotbugs, forbiddenapis, jdeps and jdeprscan. Like every boolean
setting, it is true when named with no value, and any value other than true or false is refused.
Under a strict setting, Checkstyle, PMD, detekt, ktlint, Scalastyle and scalafmt fail as their own exit code
decides, so a Checkstyle finding at severity warning is reported but does not fail the build. SpotBugs,
CodeNarc, forbiddenapis, jdeps and jdeprscan fail on any finding their report holds.
Reporting covers findings, not a tool that never ran. A linter that fails on its own configuration, and so writes no complete report, fails its step either way.
Checkstyle and PMD
Checkstyle reads ${config_ as the folder of its configuration, as the Maven and Gradle plugins define it.
A file the configuration names as ${config_ beside or below it, such as a suppressions file, is
handed to Checkstyle along with the configuration, and changing that file runs the check again. A path that
leaves the folder fails the build.
Every other ${<property>} the configuration names is a line of checkstyle., which takes the place
of the Maven plugin's propertyExpansion and Gradle's configProperties. Without the line, Checkstyle fails to
load the configuration. config_ is the one property the file cannot set. In the example above,
checkstyle. reads its severity as <property name=.
configuration may name a file outside the project, so that several projects share one configuration, and
Checkstyle still reads it as checkstyle.:
# build.jenesis/checkstyle.properties
configuration=../../shared/company.xml
A jar of custom checks or filters, a dependency of the Checkstyle plugin in Maven, joins Checkstyle's class path
when @jenesis. names it in module-info., or
<!--jenesis. in a pom..
PMD runs the rules of every priority in its rule set. jenesis. names the lowest priority it
runs, from 1, the highest, to 5, the default, as the Maven plugin's minimumPriority does; any other
value is refused.
Switching a tool off
A tool found by its file can be switched off without deleting the file. Every such setting is a boolean,
true by default, and false leaves the tool out. It is named after the part of the build the tool runs in:
| Setting | Covers |
|---|---|
jenesis. |
checkstyle, pmd, detekt, ktlint, scalastyle, scalafmt, codenarc |
jenesis. |
spotbugs, forbiddenapis, jdeps, jdeprscan |
For example, -Djenesis. keeps checkstyle. in place but skips Checkstyle,
while PMD and SpotBugs still run. Every other tool that a file of this chapter switches on has a setting of the
same kind, which its section names. A plugin of the project's own, which jenesis. names, is switched off by
-Djenesis. instead, so it shares no setting with an official plugin, whatever it is named.
Forbidden API calls
forbiddenapis finds calls that the compiled classes, the
tests' included, should not make: a method that depends on the default locale, a deprecated API, a JDK internal
or a call the project rules out. A forbiddenapis. switches it on and names the signatures to check:
# build.jenesis/forbiddenapis.properties
bundled=jdk-unsafe,jdk-deprecated,jdk-non-portable,jdk-system-out
signatures=forbidden-signatures.txt
bundled names signatures that forbiddenapis ships. jdk-unsafe, jdk-deprecated and jdk-internal are
written for one Java release, as jdk-unsafe-25, and the build appends the release the classes are compiled
for where the name leaves it out. signatures names files of the project's own signatures, relative to
forbiddenapis., in the format forbiddenapis reads:
@defaultMessage Name a thread: an unnamed one is hard to tell apart in a thread dump
java.lang.Thread#<init>(java.lang.Runnable)
| Key | Maven plugin parameter | Meaning |
|---|---|---|
bundled |
bundledSignatures |
bundled signatures, comma-separated |
signatures |
signaturesFiles |
the project's own signature files, comma-separated |
suppress |
suppressAnnotations |
annotations that silence a finding, as **. |
includes, excludes |
includes, excludes |
patterns of the class files to check |
warn |
signaturesWithSeverityWarn |
signatures reported as a warning rather than a finding |
allowmissingclasses |
failOnMissingClasses= |
true lets a class missing from the class path pass |
ignoresignaturesofmissingclasses |
ignoreSignaturesOfMissingClasses |
true skips a signature whose class is missing |
At least one of bundled and signatures is required. Any other key fails the build, and so does a file named
under signatures that does not exist. The report, reports/, holds one line per
finding: the call, the reason and where it was made.
JDK internals and removals
Two tools that ship with the JDK check what the compiled classes, the tests' included, ask of the JDK. They resolve nothing, and each is switched on by its own file, which may be empty.
A jdeps. runs jdeps --jdk-internals. It reports every JDK internal API a class uses, with the
replacement jdeps suggests:
sample.Legacy -> sun.misc.Unsafe: JDK internal API (jdk.unsupported), instead: See https://openjdk.org/jeps/260
Its one key, accept, names internal classes or packages that a project uses on purpose, as accept=,
and these are then no finding. A multi-release dependency is read as the JDK running the build would load it.
A jdeprscan. runs jdeprscan --for-removal. It reports every use of an API that the JDK has
scheduled for removal:
sample/Legacy uses deprecated method java/lang/Thread::stop()V (forRemoval=true)
removal= reports every deprecated API instead, and release= checks the deprecations of that Java
release. A class whose dependencies are not on the module's compile class path fails the check, naming them,
rather than going unscanned.
Both use the tool of the JDK the build runs on. Running a build on a newer JDK, as
-Djenesis. does, therefore shows what that JDK has encapsulated or scheduled for
removal before the code runs on it. Their reports are reports/ and
reports/, one finding per line.
Analysis inside the compiler
The linters above read sources or classes beside the compiler. Error Prone reads
neither: it is a javac plugin, so it sees the same typed syntax tree the compiler built and reports through
the compiler's own diagnostics. That is how it catches a mistake the compiler accepts, such as comparing two
strings with =.
Because it is a compiler plugin rather than a tool of its own, it is declared where compiler plugins are declared - on the module, with the tag that also declares an annotation processor:
/**
* @jenesis.plugin javac maven/com.google.errorprone/error_prone_core
*/
module demo.errorprone {
exports demo.errorprone;
}
@jenesis. resolves into the plugin scope of that compiler's own group, the
same shape a Kotlin compiler plugin uses, and javac reads that group into its processor path. An Error
Prone plugin such as NullAway is another line of exactly the same form. A coordinate written without a
version, as here, takes the newest release until pin records one.
What turns the plugin on are javac's own options, in a process-javac. of the configuration
folder like any other compiler option. Each key is one option, so the =, : and space inside one are escaped:
# build.jenesis/process-javac.properties
-XDcompilePolicy\=simple
--should-stop\=ifError\=FLOW
-J--add-exports\=jdk.compiler/com.sun.tools.javac.api\=ALL-UNNAMED
-J--add-exports\=jdk.compiler/com.sun.tools.javac.file\=ALL-UNNAMED
-J--add-exports\=jdk.compiler/com.sun.tools.javac.main\=ALL-UNNAMED
-J--add-exports\=jdk.compiler/com.sun.tools.javac.model\=ALL-UNNAMED
-J--add-exports\=jdk.compiler/com.sun.tools.javac.parser\=ALL-UNNAMED
-J--add-exports\=jdk.compiler/com.sun.tools.javac.processing\=ALL-UNNAMED
-J--add-exports\=jdk.compiler/com.sun.tools.javac.tree\=ALL-UNNAMED
-J--add-exports\=jdk.compiler/com.sun.tools.javac.util\=ALL-UNNAMED
-J--add-opens\=jdk.compiler/com.sun.tools.javac.code\=ALL-UNNAMED
-J--add-opens\=jdk.compiler/com.sun.tools.javac.comp\=ALL-UNNAMED
-Xplugin\:ErrorProne\ -Xep\:ReferenceEquality\:ERROR
| Option | Why Error Prone needs it |
|---|---|
-Xplugin:ErrorProne |
Runs the plugin, which javac does only when an option names it. What follows the name are Error Prone's own flags: -Xep:<Check>:OFF|WARN|ERROR, -XepAllErrorsAsWarnings, -XepDisableWarningsInGeneratedCode. |
-XDcompilePolicy= |
Has javac analyse every class completely before it generates code, so the checks see the analysed code rather than code already partly lowered. |
--should-stop= |
Keeps javac going through its flow analysis after an error, so the plugin reports beside the compiler. |
-J--add-exports, -J--add-opens |
Grant the plugin the compiler's internal packages, which jdk. does not export. They are options of the JVM that runs javac, so javac runs in a JVM of its own: one per compilation, or, in the daemon or under jenesis., one that every compilation with the same options shares, side by side and kept warm. |
javac reads the first two when it starts, and the exports must be in place before it does, so neither the plugin
nor an annotation processor can supply them itself. Without the -Xplugin line the declared plugin resolves and
sits unused. A pom. project declares the plugin as a
<!--jenesis. comment, in the module's POM or in a
parent POM in the project.
Formatting
Formatters are the rewriting counterpart to the linters: where a linter reads your sources and writes a
report, a formatter reads them and can rewrite them in place. A formatter reads a module's resources as well, such
as the files under src/ of a pom. project. Each formatter is switched on by a properties file
named after it, whose lines are its values; an empty file formats with the defaults:
# build.jenesis/googlejavaformat.properties
reflow=false
A value the formatter does not take fails the build, naming the ones it takes, and a changed value verifies every source again:
| File | Value | Meaning |
|---|---|---|
googlejavaformat. |
style |
google, the default, or aosp for the Android Open Source Project's four-space style |
reflow |
false leaves long strings as they are written |
|
javadoc |
false leaves Javadoc as it is written |
|
imports |
what happens to the imports: sort,remove, the default, sort, remove or none |
|
palantir. |
reflow, imports |
as for google-java-format |
openjavaformat. |
reflow, imports |
as for google-java-format; Open Java Format is a fork of Palantir Java Format with one style |
princeofspace. |
wrap-style |
balanced, the default, wide or narrow |
indent-style |
spaces, the default, or tabs |
|
indent-size |
indent units per level, 4 by default; with tabs each unit is a tab |
|
line-length |
the length wrapping aims for, 120 by default |
|
closing-paren-on-new-line |
false keeps the closing parenthesis of a wrapped argument list on its last line |
|
trailing-commas |
true adds trailing commas to multi-line enums and array literals |
|
java-version |
the language level the sources are parsed at, 17 by default |
|
eclipse. |
configuration |
the formatter profile Eclipse exports, relative to the file; without it, the Eclipse formatter's defaults |
ktlint. |
configuration |
the . that drives ktlint |
ktfmt. |
style |
meta, the default, google or kotlinlang |
imports |
sort keeps unused imports; sort,remove, the default, removes them as well |
|
scalafmt. |
configuration |
the . that drives scalafmt |
Where no configuration folder holds an eclipse., an eclipse-formatter. in a configuration folder
switches the Eclipse formatter on alone, as its profile. The formatter runs from org. in a plain
JVM, with no Eclipse installation.
ktlint and scalafmt both check and format, and the one file of each, or its conventional . or
., switches on both. They are switched off apart: jenesis. leaves out the
linting and jenesis. the formatting, and the same holds for scalafmt.
Other files with Spotless
A spotless. formats files of any kind with Spotless. Its lines
name sets of files, each with the Spotless steps applied to them in order:
# build.jenesis/spotless.properties
json.target=*.json
json.steps=jacksonJson,endWithNewline
markdown.target=*.md
markdown.steps=flexmark,trimTrailingWhitespace,endWithNewline
<set>. names the globs a file of the module's sources or resources matches, and <set>. the steps;
<set>. configures one of them, as java.:
| Step | Options |
|---|---|
trimTrailingWhitespace, endWithNewline, formatAnnotations |
none |
leadingTabsToSpaces, leadingSpacesToTabs |
size, 4 by default |
replaceRegex |
regex, and replacement, empty by default |
importOrder |
order, the comma-separated import groups |
jacksonJson, jacksonYaml, flexmark |
version of Jackson or flexmark |
removeUnusedImports |
version of google-java-format |
googleJavaFormat |
version, style (GOOGLE or AOSP), reflowLongStrings, reorderImports, formatJavadoc |
palantirJavaFormat |
version, style (PALANTIR, AOSP or GOOGLE), formatJavadoc |
princeOfSpace |
version, wrapStyle, indentStyle, indentSize, lineLength, closingParenOnNewLine, trailingCommas, javaLanguageLevel |
ktfmt |
version, style (META, GOOGLE or KOTLINLANG), maxWidth, blockIndent, continuationIndent, removeUnusedImports |
ktlint |
version, and any . property, as indent_ |
scalafmt |
version, which it requires, scalaMajorVersion, and any key of ., as maxColumn |
licenseHeader |
header, its lines separated by \n, and delimiter |
A key, step or option the plugin does not take fails the build, naming those it takes. Each step that needs a tool
resolves it in a group of its own, as spotless:jacksonjson, so no two tools share a version; a tool floats on its
newest release unless version names one, and is pinned like any other. The plugin reads no other tool's file: a
Spotless setup moves into spotless. as a whole, its options handed to each step as Spotless hands them.
Spotless's Eclipse steps, which resolve from Eclipse's own repositories, and the steps that need Node.js or a native
program are not offered. A set running a Java, Kotlin or Scala formatter, or licenseHeader, makes Spotless that tool
of the build, so the build refuses it beside that tool's own file, naming both; any other set runs beside them.
Two formatters would fight over the same sources. A build that finds the files of two Java formatters fails,
naming them, and so does a ktfmt. beside a ktlint that formats the same Kotlin sources. A profile that
brings in one formatter therefore switches the other off in its jenesis-<profile>., as
jenesis. or jenesis.. Each formatter has its setting of
jenesis.: googlejavaformat, palantir, openjavaformat, princeofspace, eclipse, spotless, ktlint, ktfmt
and scalafmt.
Verify mode, and how to reformat
Every formatter runs in verify mode by default, so a normal build never touches your sources. Instead it
fails the build when a file is not already formatted, which makes it a continuous-integration gate. Indent
a source file with a few spare spaces and rebuild: the format step fails.
To apply the formatter and rewrite your sources in place, run the build with the rewrite switch:
java -Djenesis.format.rewrite=true build/jenesis/Make.java
The switch flips every formatter from verifying to rewriting, and the same switch applies OpenRewrite's recipes and writes the licence headers. After a rewrite, a plain build passes the verify gate again.
codenarc.xml lints but nothing reformats.
Rewriting with recipes
OpenRewrite applies recipes to the Java sources: a method renamed, an API
migrated, an unused import removed. Its own file, a rewrite. in a configuration folder, switches it on and
declares the recipes the project runs:
# build.jenesis/rewrite.yml
type: specs.openrewrite.org/v1beta/recipe
name: demo.Modernize
recipeList:
- org.openrewrite.java.ChangeMethodName:
methodPattern: java.lang.String trim()
newMethodName: strip
OpenRewrite runs before the Java formatter, so what a recipe writes is formatted afterwards. Like a formatter
it verifies by default: a source a recipe would change fails the build, printing the change as a diff, and
-Djenesis. applies it.
- return name.trim();
+ return name.strip();
The recipes demo.Modernize change 1 file - run with -Djenesis.format.rewrite=true to apply them
An openrewrite. takes the place of the file where more is wanted:
| Key | Meaning |
|---|---|
configuration |
a rewrite., relative to openrewrite., every recipe of which runs |
recipes |
the recipes to run, comma-separated, instead of every recipe of the rewrite.: recipes of OpenRewrite, of a recipe library the module names, or of the rewrite. |
At least one of them is required, and any other key is refused. With recipes and no configuration,
OpenRewrite runs a recipe of its own, as recipes=.
A recipe of OpenRewrite's own Java module needs nothing more. A recipe library is named for the plugin to load
beside OpenRewrite, as @jenesis.
in module-info., and resolves with it in the group openrewrite:tool. The module's dependencies are
OpenRewrite's class path, so a recipe that matches a type of a library the module uses finds it. A recipe that
would add, delete or move a file fails the build, and -Djenesis. switches OpenRewrite
off.
Licence headers
A licenseheader. in a configuration folder holds, as its text key, the header every Java, Kotlin,
Scala and Groovy source of the module starts with, module-info. and package-info. included. A header
written as plain text starts a source as a block comment, and one written as a comment already starts it as it
stands. \n separates its lines, and a trailing \ continues the value on the next line:
text=Copyright 2026 the original author or authors.\n\n\
Licensed under the Apache License, Version 2.0.
The file takes no other key. The header is taken exactly as it stands, a year included: a source without it, or
with a different one, fails the build, naming the file. The header is checked or written before any formatter
runs. Under
-Djenesis. the header is inserted as it stands, or replaces a leading comment that names a
copyright or a licence, so a rewrite gives the same sources whenever it runs. Generated sources are not checked,
and jenesis. switches the check off.
Without text, the header is derived from what the project declares: the one licence of its pom. or its
project., named by its SPDX identifier, and its copyright where one is declared. An empty
licenseheader. beside a project. holding
license.apache_2_0.name=Apache License, Version 2.0
license.apache_2_0.url=https://www.apache.org/licenses/LICENSE-2.0.txt
copyright=2026 the original author or authors
starts every source with these two lines:
// SPDX-FileCopyrightText: 2026 the original author or authors
// SPDX-License-Identifier: Apache-2.0
A project that declares no licence, more than one, or one without a known SPDX identifier fails the build, naming
what it found. An alias/ line in spdx. gives a licence its identifier.
Where the reports land
Every tool writes its findings into a reports/ folder under its step's output, for example
reports/, reports/, reports/, reports/,
reports/. You rarely need the exact path, because a stage build collects every report from every module into one place, each kind in its own
subfolder:
target/stage/reports/output/<kind>/<module>/
So target/ is the Checkstyle report for the
module under sources/, and coverage reports land under target/ the
same way.
Code coverage
Coverage is a test observation: JaCoCo wraps the test run and records which code the tests touched. A
jacoco. in a configuration folder switches it on, in every test module where the file is found:
# build.jenesis/jacoco.properties
minimum.method=0.6
The project-wide build. works for every layout; a pom. project can also scope the file to its tests
with src/.
With coverage on, the test step is launched with the JaCoCo agent attached as a -javaagent. It
instruments the run without touching your sources and writes its execution data (jacoco.); a downstream
report step renders an HTML and XML report under reports/, over the classes of the module the tests
name by @jenesis., or the artifact a pom. module's tests belong to, never the compiled tests
themselves nor another module of the project the tested one requires. Open the index. to browse coverage
line by line, beside the source of each class. JaCoCo's CLI resolves in the tool group of its plugin, jacoco:tool, apart from your
dependencies, and its agent in jacoco:agent. The agent writes the data the CLI reads, so it follows the release the tool group
pins for the CLI: a pin of jacoco:tool/ alone runs the tests under that
version's agent as well, until pin records both.
An empty jacoco. only reports: a method your tests never reach shows up as uncovered, and the
build stays green. Lines in the file set limits on the module's coverage, as the check goal of jacoco-maven-plugin
does for a bundle:
| Key | Limit |
|---|---|
minimum. |
the least covered ratio, from 0 to 1, such as minimum. |
maximum. |
the most items left uncovered, such as maximum. |
The counters are JaCoCo's: instruction, branch, line, complexity, method and class. A limit that is not
met fails the build once the report is rendered, naming the limit and what the tests reached:
a covered ratio of 0.9 of methods is not met: 2 of 3 covered, a ratio of 0.6667
A counter with nothing to count, such as branch in code without a branch, meets every limit. An unknown key, or a
value that is no ratio or count, fails the build naming the valid ones. Set -Djenesis. to
suppress coverage even when the file is present.
Recording the tests with Java Flight Recorder
A jfr. file in a configuration folder records the test JVM with Java Flight Recorder, which ships
with the JDK, so nothing is resolved. Each line is an option of the recording, as -XX:StartFlightRecording
takes it:
# jfr.properties
settings=profile
maxsize=100m
The build names the file itself and writes it into the test step's reports, so it is staged with the others
under target/. Open it in JDK Mission Control or summarise it with
jfr summary. A filename line is refused, and so is a value holding a comma, which would split the options.
Because the file lives in a configuration folder, a profile switches the recording on for one build:
build. records only under -Djenesis.. Changing the
file runs the tests again. Set -Djenesis. to suppress the recording even when the file is
present.
Profiling the tests with async-profiler
async-profiler samples what the test JVM spends its time on.
An asyncprofiler. in a configuration folder attaches it to the JVM the tests run in, in every test
module where the file is found. Each line is an option of the profiler, as event= or interval=, or an
option without a value, as threads:
# build.jenesis/profiling/asyncprofiler.properties
event=cpu
interval=1ms
threads
The build names the file the profile is written to, so a file line is refused, and so is a value holding a
comma. It writes reports/, a flame graph to open in a browser, staged under
target/. An option that selects another format writes
tests., tests., tests. or tests. instead (jfr, collapsed, flat, traces,
summary, otlp).
The agent, tools., carries the profiler's native library and resolves in the group
asyncprofiler:agent; the tests' JVM is granted native access for it. async-profiler ships its library for Linux
on x64 and arm64 and for macOS, and elsewhere the build fails. Kept in a profile folder, as above, the file
profiles only the builds run with -Djenesis., and -Djenesis.
switches it off.
Narrowing a test run
While you are chasing one failure, running the whole suite each time is noise. Two properties narrow what the test step executes:
java -Djenesis.test.filter='calc.*Test#addsTwo' build/jenesis/Make.java
java -Djenesis.test.tag=fast+-slow,io+-slow build/jenesis/Make.java
jenesis. takes a comma-separated list of <classRegex>[#<method>] entries and runs only what
matches. The expression matches the whole class name and takes the place of the default naming (*Test,
*IT and the rest), so . runs classes that the naming would leave out. It also takes the place of the
naming's JUnit 4 check that a class holds tests, so under JUnit 4 every class it matches runs, a nested helper
included; where the default naming fits, leave classes out with jenesis. instead, which keeps the
check. jenesis. selects by tag, in a syntax of its own described below.
An entry applies to every test module, and a test module where it matches no test fails the build. In a
project with several test modules, lead the entry with a module's folder and a / to keep it to that module's
tests:
java -Djenesis.test.filter='greeter-test/.*GreeterTest#prefix_is_a_greeting' build/jenesis/Make.java
The folder is the one a +<module> selector names, and a nested folder such as libs/ works too.
In a pom. project it is the folder of the module's pom. relative to the root, so the root module's
entry is written /, with nothing before the slash.
A test module that no entry reaches runs no tests rather than failing, while one an entry does reach still
fails when nothing there matches.
jenesis. leaves classes out instead. It takes the same entries without a #<method>, and the
default naming or the filter stays in force for everything else:
java -Djenesis.test.exclude='.*IntegrationTest' build/jenesis/Make.java
A test module whose every selected class is left out runs no tests.
Selecting tests by tag
The tag selection is framework neutral: it is written the same way whatever the tests run on, and Jenesis
translates it into the framework's own mechanism, so a selection keeps working when a project moves from one
framework to another and nobody has to learn JUnit's tag expressions or TestNG's group lists. It is also built
for the command line: it uses three characters that no shell interprets - no !, &, |, parentheses or
spaces - so a selection is typed as it stands, never quoted, and reads the same in bash, zsh and a CI step.
| Write | Means |
|---|---|
, |
or: separates alternatives, and a test runs where it matches any of them |
+ |
and: joins tags within an alternative, for the tests carrying all of them |
- before a tag |
not: the tests that do not carry that tag |
| Selection | Runs |
|---|---|
fast |
the tests tagged fast |
fast,io |
the tests tagged fast or io |
fast+io |
the tests tagged both fast and io |
-slow |
every test that is not tagged slow |
fast+-slow,io+-slow |
the tests tagged fast or io that are not tagged slow |
-container+-soak |
the tests tagged neither container nor soak |
-container,-soak |
every test that is not tagged both container and soak |
release,-container |
the tests tagged release, and every test that is not tagged container |
Every selection a tag expression can make can be written this way, as alternatives each joining tags and negated
tags. A hyphen inside a tag, as in slow-io, is part of its name; - negates only at the start of one. A selection
that uses anything else, or an alternative that asks for a tag and its negation at once, fails the build with the
form spelt out.
Jenesis translates the selection for the framework that runs the tests:
| Framework | A tag is | Translated into | Selections it can run |
|---|---|---|---|
| JUnit Platform | a @Tag value |
one --include-tag expression |
every selection |
| TestNG | a group | -groups and -excludegroups |
alternatives of at most one group each, all leaving out the same groups |
| JUnit 4 | a @Category class, named in full as com. |
an IncludeCategories filter per tag and one ExcludeCategories filter |
one alternative of any tags, or alternatives of at most one category each, all leaving out the same categories |
The framework is found for each module from the tests' own dependencies, so a project whose modules test with
different frameworks is selected with one expression: -Djenesis. runs the tests tagged slow in a
JUnit Platform module and the group slow in a TestNG module alike. Under JUnit 4 a tag is a class name, and JUnit
fails the run when the class does not exist or when the selection matches no test of the module. A selection a framework cannot
run fails the build with the form it would accept. A framework plugged in through the TestFramework interface
translates the selection in its own tags method, and one that does not implement it refuses any selection. A
project declares such a framework as a plugin of the hook point test (see
Extending the build), and the frameworks it
declares are consulted before the built-in ones.
A narrowed run is still the same step, so its result is remembered together with what it covered, and every
later run adds to that memory until the tests or what they test change. A request runs only what no remembered
run covered: after fast, asking for fast,io runs the tests tagged io that are not tagged fast, asking for
fast again runs nothing, a run of fast covers a request for fast+io, and a run of every test covers any
request. A run that left tests out covers only an alternative that leaves them out too. The filter and the exclusion are compared as they are written, so a different
one runs the tests again and starts a new memory.
-Djenesis.test.force=true. It forgets what earlier runs covered and runs the whole selection. Narrowing belongs on a
developer machine, though: a build that populates a
shared cache should run the full suite, or a narrowed
result can be served to someone asking for more.
Running only the tests a change affects
Jenesis already skips a module's whole test step when none of that module's inputs changed. Test selection
is the finer-grained companion: within a module that did change, it runs only the test classes the change
can reach and leaves the rest cached. Turn it on with -Djenesis.:
java -Djenesis.project.watch=true -Djenesis.test.mode=incremental build/jenesis/Make.java
jenesis. takes five values:
| Value | What runs |
|---|---|
alphabetic (default) |
Every test, the classes handed to the runner in order of their names. |
incremental |
Only the tests a change reaches. |
prioritized |
Every test, the ones a change reaches handed to the runner first and the rest after them. |
failed |
Only the classes that failed in the run before. |
failedfirst |
Every test, the classes that failed in the run before handed to the runner first and the rest after them. |
Any other value fails the build with the valid ones listed. The JUnit Platform runs the classes in the order
it is handed them, so under prioritized the results of the tests a change reaches appear before the rest
has run. A filter, an exclusion and a tag selection each switch incremental off, so such a run runs every
test it selects; prioritized and failedfirst still hand their classes over first.
failed and failedfirst turn on the reports of jenesis. and read from them which test
methods failed, for the JUnit Platform and TestNG. They keep them for the module's next run, a failed run
included, as long as the module's test configuration is unchanged, and rerun whole classes. Where nothing
failed or nothing is recorded, both run every test. JUnit 4 writes no report they read, so under JUnit 4 both
run every test in order of their names.
On each run the test step builds a class-to-test dependency graph from the compiled bytecode and records a
per-class content hash. On the next run it diffs the hashes, takes the classes whose bytecode changed and
walks the graph to the tests that reach them. A change that reaches no test runs nothing under incremental,
and a run with no earlier record, or a non-class change (a resource, a dependency), runs every test in order
of their names.
Test selection is meant mainly for watching a project (see Building & running), where the build re-runs on every save and a narrowed test pass keeps the feedback loop tight.
build, or prioritized or failedfirst, which run
every test.
Mutation testing
Coverage tells you which lines a test executed; mutation testing tells you which behaviours a test actually
checks. PIT (pitest) seeds small faults into your code (a + becomes a -, a
return value is replaced with a constant), re-runs the tests against each mutant, and reports which mutants
the tests killed and which survived. A surviving mutant is a change to the program that no test
noticed.
A pitest. in a configuration folder switches PIT on, in every test module where the file is found:
the suite runs as usual and PIT then re-runs it against mutants of the code under test, to assess how good it
is. PIT mutates the module the tests name by @jenesis., or the artifact a pom. module's tests belong
to, and never the tests themselves. The file carries the options PIT needs:
# build.jenesis/pitest.properties
targetTests=calctest.* # which tests to run against the mutants
outputFormats=XML,HTML # report formats (an optional `mutators` key selects a mutator set)
| Key | Meaning | Default |
|---|---|---|
targetClasses |
globs of the classes to mutate | every package of the tested module |
targetTests |
globs of the tests to run against the mutants | * |
outputFormats |
the report formats, of XML, HTML and CSV |
XML |
mutators |
the mutators or mutator groups PIT applies | PIT's own default |
failWhenNoMutations |
fail when PIT finds nothing to mutate | false |
An unknown key, or a format that is not one of the three, fails the build naming the ones that exist. PIT
refuses * for targetClasses, as that would select PIT itself.
PIT and its JUnit 5 plugin resolve in the tool group of the PIT plugin, pitest:tool, apart from your
dependencies. PIT runs the tests with the JUnit Platform launcher of the version the test module pins or
resolved, so it lines up with the test framework you use. The report lands under reports/, with the
source of every mutated class in its HTML, and
-Djenesis. suppresses the run while keeping the file in place.
API compatibility
Coverage and mutation testing ask whether your tests are any good. API compatibility asks whether the jar you are about to publish still works for everyone who compiled against the last one. japicmp answers by comparing byte code, which is the level that matters: a caller linked against class files, so a removed method, a narrowed return type or a tightened modifier is what breaks them.
A japicmp. in a configuration folder switches japicmp on, in every module but a test module where
the file is found. The file may be empty. Then japicmp compares the module's fresh jar
against the last release of that module's own coordinate, so the check follows your releases rather than
being re-pointed by hand. A baseline key names another artifact, read by how many slashes it carries:
baseline=com.example/library # the latest release
baseline=com.example/library/1.2.3 # that version
baseline=<repository>/com.example/library/1.2.3 # that version, from the repository of that name
A module with no Maven coordinate has nothing to default to and says so. The file is read per module, so a
project-wide japicmp. without a baseline gives every module its own coordinate - a baseline
there would point them all at one artifact, so a per-module baseline belongs in that module's own
configuration folder. A test module, such as the tests of a pom. project, has no release of its own and is
never compared.
The remaining keys map onto japicmp's own options:
| Key | Effect | Default |
|---|---|---|
access |
lowest visibility to compare (public, protected, package, private) |
japicmp's own |
include / exclude |
comma-separated package or class filters | none |
format |
xml, html, or both |
xml |
ignore-missing-classes |
tolerate types the baseline's own dependencies would have provided | true |
only-incompatible / only-modified |
narrow what the report lists | false |
semantic-versioning |
report the version increment the changes call for | false |
error-on-binary-incompatibility |
fail the build on a binary-incompatible change | false |
error-on-source-incompatibility |
fail the build on a source-incompatible change | false |
error-on-modifications |
fail the build on any change at all | false |
error-on-semantic-incompatibility |
fail the build on a semantic-versioning violation | false |
An unknown key fails the build and lists the ones that exist.
Like the linters, the check only reports by default: it writes reports/ and
keeps the build green, so you see what changed before you decide to enforce it. Turning on a gate makes the
failure name the change that caused it:
E: There is at least one incompatibility: library.Library.farewell(java.lang.String):METHOD_REMOVED
japicmp and the baseline artifact resolve in the tool group of the japicmp plugin, japicmp:tool, kept apart from the module's own
dependencies; the baseline resolves without its transitive dependencies, because only its own byte code
is compared. It is a released artifact like any other, so pin records it with a checksum alongside the
tool - one line, not a closure. The plugin resolves both with the project's repositories.
-Djenesis. suppresses the comparison while keeping the file in place.
revapi beside japicmp
revapi compares the same two jars and classifies every difference by how severe it is for
a caller, binary and source alike. A revapi. switches it on, in every module but a test module where
the file is found, and revapi compares against the same baseline: its baseline key reads exactly as japicmp's, and without one it is the last release of the
module's own coordinate.
# build.jenesis/revapi.properties
severity=non-breaking
configuration=revapi.json
| Key | Effect | Default |
|---|---|---|
baseline |
the artifact to compare against, as for japicmp | the module's own last release |
severity |
the least severe difference reported: equivalent, non-breaking, potentially-breaking or breaking |
potentially-breaking |
configuration |
a JSON file holding revapi's own configuration, relative to revapi. |
none |
That file is revapi's own, an array of {"extension": . objects, so the
differences a release accepts stay in revapi's notation, as a revapi. list:
[{"extension": "revapi.differences", "configuration": {"ignore": true, "differences": [
{"code": "java.method.removed", "old": "method java.lang.String library.Library::farewell(java.lang.String)",
"justification": "Deprecated for two releases."}]}}]
Any other key fails the build, as does a configuration naming a file that is no JSON array. revapi reports like
a linter: reports/ holds one entry per difference, with its code and classification, and a
[FINDINGS] line counts them.
The build stays green on those findings unless -Djenesis. fails it on any difference
reported, and -Djenesis. skips revapi. It resolves in the tool group of its plugin,
revapi:tool, with revapi-java, revapi-basic-features and revapi-reporter-json and what they depend on,
beside the baseline.
Seeing every failure at once
A multi-module build fans out: each module's tests are their own branch of the graph, and those branches run concurrently. By default the run reports the first failure and stops there, which is what you want when one broken module means the rest is moot. When you would rather see the whole picture (a CI run, or a change that touches every module), let the failures aggregate:
java -Djenesis.executor.aggregate=true build/jenesis/Make.java
Every independent branch then runs to completion and the build fails once, reporting every module that broke rather than stopping at the first. A step whose input failed is still skipped either way: only independent failures aggregate.
Pinning the tool chain
Every tool above that the build downloads floats a RELEASE version in the tool group of its plugin until you
pin it, so a first build downloads the latest and later builds reuse the cache; a plugin's own jars are pinned
apart, in the group of its name. jdeps, jdeprscan, Java Flight Recorder and the licence header check resolve
nothing. For a reproducible, checksum-verified tool chain, run
java build/: it records each resolved tool jar with its SHA-256 exactly as it pins
your compilers and dependencies (see Pinning & bills of materials). Expect a long list -
a linter's own closure can run to a hundred artifacts - which is what makes the tool chain reproducible. A
tool that only a profile turns on is pinned by running pin with that profile active.