{"id":26629927,"url":"https://github.com/gradlex-org/java-module-testing","last_synced_at":"2025-04-10T15:22:54.468Z","repository":{"id":64863372,"uuid":"434168441","full_name":"gradlex-org/java-module-testing","owner":"gradlex-org","description":"Gradle plugin to turn JVM Test Suites into Blackbox or Whitebox Test Suite for Java Modules","archived":false,"fork":false,"pushed_at":"2025-04-04T07:46:30.000Z","size":557,"stargazers_count":17,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-04T08:29:40.047Z","etag":null,"topics":["gradle-plugin","java","java-modules","jpms","testing"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gradlex-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-02T10:03:04.000Z","updated_at":"2025-04-04T07:46:33.000Z","dependencies_parsed_at":"2023-11-16T21:02:32.843Z","dependency_job_id":"dcaf4d71-5ddf-47f0-b33b-ecd5f8ddf3b7","html_url":"https://github.com/gradlex-org/java-module-testing","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradlex-org%2Fjava-module-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradlex-org%2Fjava-module-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradlex-org%2Fjava-module-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradlex-org%2Fjava-module-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gradlex-org","download_url":"https://codeload.github.com/gradlex-org/java-module-testing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248243421,"owners_count":21071054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gradle-plugin","java","java-modules","jpms","testing"],"created_at":"2025-03-24T13:16:16.482Z","updated_at":"2025-04-10T15:22:54.449Z","avatar_url":"https://github.com/gradlex-org.png","language":"Java","readme":"# Java Module Testing Gradle plugin\n\n[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fgradlex-org%2Fjava-module-testing%2Fbadge%3Fref%3Dmain\u0026style=flat)](https://actions-badge.atrox.dev/gradlex-org/java-module-testing/goto?ref=main)\n[![Gradle Plugin Portal](https://img.shields.io/maven-metadata/v?label=Plugin%20Portal\u0026metadataUrl=https%3A%2F%2Fplugins.gradle.org%2Fm2%2Forg%2Fgradlex%2Fjava-module-testing%2Forg.gradlex.java-module-testing.gradle.plugin%2Fmaven-metadata.xml)](https://plugins.gradle.org/plugin/org.gradlex.java-module-testing)\n\nA Gradle 7.4+ plugin to turn a [JVM Test Suite](https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html#sec:jvm_test_suite_configuration)\ninto a **Blackbox** or **Whitebox** Test Suite for Java Modules.\n\nThis plugin is maintained by me, [Jendrik Johannes](https://github.com/jjohannes).\nI offer consulting and training for Gradle and/or the Java Module System - please [reach out](mailto:jendrik.johannes@gmail.com) if you are interested.\nThere is also my [YouTube channel](https://www.youtube.com/playlist?list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE) on Gradle topics.\n\nIf you have a suggestion or a question, please [open an issue](https://github.com/gradlex-org/java-module-testing/issues/new).\n\n# Java Modules with Gradle\n\nIf you plan to build Java Modules with Gradle, you should consider using these plugins on top of Gradle core:\n\n- [`id(\"org.gradlex.java-module-dependencies\")`](https://github.com/gradlex-org/java-module-dependencies)  \n  Avoid duplicated dependency definitions and get your Module Path under control\n- [`id(\"org.gradlex.java-module-testing\")`](https://github.com/gradlex-org/java-module-testing)  \n  Proper test setup for Java Modules\n- [`id(\"org.gradlex.extra-java-module-info\")`](https://github.com/gradlex-org/extra-java-module-info)  \n  Only if your (existing) project cannot avoid using non-module legacy Jars\n\n[Here is a sample](https://github.com/gradlex-org/java-module-testing/tree/main/samples/use-all-java-module-plugins)\nthat shows all plugins in combination.\n\n[In episodes 31, 32, 33 of Understanding Gradle](https://github.com/jjohannes/understanding-gradle) I explain what these plugins do and why they are needed.\n[\u003cimg src=\"https://onepiecesoftware.github.io/img/videos/31.png\" width=\"260\"\u003e](https://www.youtube.com/watch?v=X9u1taDwLSA\u0026list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)\n[\u003cimg src=\"https://onepiecesoftware.github.io/img/videos/32.png\" width=\"260\"\u003e](https://www.youtube.com/watch?v=T9U0BOlVc-c\u0026list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)\n[\u003cimg src=\"https://onepiecesoftware.github.io/img/videos/33.png\" width=\"260\"\u003e](https://www.youtube.com/watch?v=6rFEDcP8Noc\u0026list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)\n\n[Full Java Module System Project Setup](https://github.com/jjohannes/gradle-project-setup-howto/tree/java_module_system) is a full-fledged Java Module System project setup using these plugins.  \n[\u003cimg src=\"https://onepiecesoftware.github.io/img/videos/15-3.png\" width=\"260\"\u003e](https://www.youtube.com/watch?v=uRieSnovlVc\u0026list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE)\n\n# How to use?\n\nFor a quick start, you can find some samples here:\n* [samples/use-all-java-module-plugins](samples/use-all-java-module-plugins)\n* [samples/use-only-java-module-testing-plugin](samples/use-only-java-module-testing-plugin)\n* [samples/use-with-test-fixtures](samples/use-with-test-fixtures)\n\nFor general information about how to structure Gradle builds and apply community plugins like this one to all subprojects\nyou can check out my [Understanding Gradle video series](https://www.youtube.com/playlist?list=PLWQK2ZdV4Yl2k2OmC_gsjDpdIBTN0qqkE).\n\n## Plugin dependency\n\nAdd this to the build file of your convention plugin's build\n(e.g. `build-logic/build.gradle(.kts)` or `buildSrc/build.gradle(.kts)`).\n\n```\ndependencies {\n    implementation(\"org.gradlex:java-module-testing:1.6\")\n}\n```\n\n## Apply the plugin\n\nIn your convention plugin, apply the plugin.\n\n```\nplugins {\n    id(\"org.gradlex.java-module-testing\")\n}\n```\n\n## Blackbox Test Suites\n\nThe plugin automatically turns [JVM Test Suites](https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html) into _Blackbox Test Suites_ if the `src/\u003ctest-suite-name\u003e/module-info.java` file exists.\nA blackbox test suite is a separate module itself.\nSee documentation on [JVM Test Suites](https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html#sec:jvm_test_suite_configuration) for more details on creating and configuring test suites.\n\n## Whitebox Test Suites\n\nThe plugin automatically turns [JVM Test Suites](https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html) **without** `module-info.java` file into _Whitebox Test Suites_.\nWhitebox Test Suites might require additional configuration, which can be done like this:\n\n```\njavaModuleTesting.whitebox(testing.suites[\"test\"]) {\n    requires.add(\"org.junit.jupiter.api\")\n    // opensTo.add(\"org.junit.platform.commons\") \u003c-- opensTo 'org.junit.platform.commons' is done by default\n    // exportsTo.add(\"...\")\n}\n```\n\nSee documentation on [JVM Test Suites](https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html#sec:jvm_test_suite_configuration) for more details on creating and configuring test suites.\n\nAlternatively, you can put the `requires` into a `module-info.java` file using the same notation that you would use for blackbox tests.\nFor this, you need to create the file in `\u003csrc-set-location\u003e/java9/module-info.java`. For example:\n\n```\nsrc\n  ├── main\n  │   └── java\n  │       ├── module-info.java\n  │       └── ...\n  └── test\n      ├── java\n      │   └── ...\n      └── java9\n          └── module-info.java\n              | module org.example.app.test {\n              |   requires org.example.app; // 'main' module into which the tests are patched\n              |   requires org.junit.jupiter.api;\n              | }\n```\n\nA whitebox _test source set_ does **not** have a `module-info.java`.\nInstead, 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.\nAdditional `requires` for the test are defined as shown above.\nIf the _sources under test_ are located in a different source set (not `main`), this can be configured via `sourcesUnderTest.set(\"source-set-name\")`.\n\n## Classpath Test Suites\n\nAn alternative variant of \"whitebox\" testing is to run testing on the classpath and ignore **all** module information.\nThis is what [Gradle does without this plugin](https://docs.gradle.org/current/userguide/java_testing.html#whitebox_unit_test_execution_on_the_classpath).\nBy default, this plugin replaces this with the [Whitebox Test Suite setup](#whitebox-test-suites), which should be the preferred testing approach.\nIf you still need to use the classpath-based setup for a Test Suite, you may configure it as follows: \n\n```\njavaModuleTesting.classpath(testing.suites[\"test\"])\n```\n\nA reason to do testing like this is if you need to utilise testing libraries (e.g. for mocking) that do not work with the Module System at all.\n\n# What does the plugin do?\n\nThe plugin rewires the inputs of test compilation (`:compileTestJava`) and test runtime (`:test`).\nThis includes configuring the Module Path and adding patch parameters in the case of whitebox testing.\n\n## Blackbox Test\n\nChanges for test runtime (`:test`):\n- Normally, the test classes are loaded from a `classes` folder\n- 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.\n\n## Whitebox Test\n\nChanges for test compilation (`:compileTestJava`):\n- Normally, Gradle would not use the Module Path, as there is no `module-info.java` in the source set\n- Now, a Module Path is computed for the compilation. \n  Using `--patch-module`, the test classes are compiled as an addition to the main module.\n\nChanges for test runtime (`:test`):\n- Normally, Gradle would not run its test runner as Module, as there is no `module-info.class` as part of the compiled tests.\n- Now, the main and test classes are both used as locations for test discovery.\n  By this, Gradle will find the `module-info.class` of the main module for the tests.\n  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.\n\n# Disclaimer\n\nGradle and the Gradle logo are trademarks of Gradle, Inc.\nThe GradleX project is not endorsed by, affiliated with, or associated with Gradle or Gradle, Inc. in any way.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgradlex-org%2Fjava-module-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgradlex-org%2Fjava-module-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgradlex-org%2Fjava-module-testing/lists"}