A Gradle 7.4+ plugin to turn a JVM Test Suite into a Blackbox or Whitebox Test Suite for Java Modules.
This plugin is maintained by me, Jendrik Johannes. I offer consulting and training for Gradle and/or the Java Module System - please reach out if you are interested. There is also my YouTube channel on Gradle topics.
If you have a suggestion or a question, please open an issue.
If you plan to build Java Modules with Gradle, you should consider using these plugins on top of Gradle core:
id("org.gradlex.java-module-dependencies")
Avoid duplicated dependency definitions and get your Module Path under controlid("org.gradlex.java-module-testing")
Proper test setup for Java Modulesid("org.gradlex.extra-java-module-info")
Only if your (existing) project cannot avoid using non-module legacy Jars
Here is a sample that shows all plugins in combination.
Full Java Module System Project Setup is a full-fledged Java Module System project setup using these plugins.
For a quick start, you can find some samples here:
For general information about how to structure Gradle builds and apply community plugins like this one to all subprojects you can check out my Understanding Gradle video series.
Add this to the build file of your convention plugin's build
(e.g. build-logic/build.gradle(.kts)
or buildSrc/build.gradle(.kts)
).
dependencies {
implementation("org.gradlex:java-module-testing:1.0")
}
In your convention plugin, apply the plugin.
plugins {
id("org.gradlex.java-module-testing")
}
To turn the existing JVM Test Suite integtest ito a Blackbox Test Suite:
javaModuleTesting.blackbox(testing.suites["integtest"])
You can create and/or configure a different test suite as long as you wrap it in javaModuleTesting.blackbox(...)
.
See documentation on JVM Test Suites
for more details.
It is expected that a blackbox test source set has its own module-info.java
.
A blackbox test suite is a separate module itself.
To turn the existing JVM Test Suite test ito a Whitebox Test Suite:
javaModuleTesting.whitebox(testing.suites["test"]) {
requires.add("org.junit.jupiter.api")
opensTo.add("org.junit.platform.commons")
}
You can create and/or configure a different test suite as long as you wrap it in javaModuleTesting.whitebox(...)
.
See documentation on JVM Test Suites
for more details.
It is expected that a whitebox test source set does not have a module-info.java
.
Instead, the main and test classes will be patched together and the test will run in the main module which now includes the test classes as well.
Additional requires
for the test are defined as shown above.
If the sources under test are located in a different source set (not main
), this can be configured via sourcesUnderTest.set("source-set-name")
.
The plugin rewires the inputs of test compilation (:compileTestJava
) and test runtime (:test
).
This includes configuring the Module Path and adding patch parameters in the case of whitebox testing.
Changes for test runtime (:test
):
- Normally, the test classes are loaded from a
classes
folder - Now, the test classes are packaged into a module
jar
together with the test resources. Otherwise, test resources would not be visible to the test module at runtime.
Changes for test compilation (:compileTestJava
):
- Normally, Gradle would not use the Module Path, as there is no
moudle-info.java
in the source set - Now, a Module Path is computed for the compilation.
Using
--patch-module
, the test classes are compiled as an addition to the main module.
Changes for test runtime (:test
):
- Normally, Gradle would not run its test runner as Module, as there is no
moudle-info.class
as part of the compiled tests. - Now, the main and test classes are both used as locations for test discovery.
By this, Gradle will find the
moudle-info.class
of the main module for the tests. Using--patch-module
, main classes, main resources, test classes, and test resources folders are all merged to be treated as one module during test runtime.
Gradle and the Gradle logo are trademarks of Gradle, Inc. The GradleX project is not endorsed by, affiliated with, or associated with Gradle or Gradle, Inc. in any way.