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 control
• id("org.gradlex.java-module-testing")
  Proper test setup for Java Modules
• id("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:

• samples/use-all-java-module-plugins
• samples/use-only-java-module-testing-plugin
• samples/use-with-test-fixtures

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.2.2")
}

In your convention plugin, apply the plugin.

plugins {
    id("org.gradlex.java-module-testing")
}

The plugin automatically turns JVM Test Suites into Blackbox Test Suites if the src/<test-suite-name>/module-info.java file exists. A blackbox test suite is a separate module itself. See documentation on JVM Test Suites for more details on creating and configuring test suites.

The plugin automatically turns JVM Test Suites without module-info.java file into Whitebox Test Suites. Whitebox Test Suites might require additional configuration, which can be done like this:

javaModuleTesting.whitebox(testing.suites["test"]) {
    requires.add("org.junit.jupiter.api")
    // opensTo.add("org.junit.platform.commons") <-- opensTo 'org.junit.platform.commons' is done by default
}

See documentation on JVM Test Suites for more details on creating and configuring test suites.

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.