Add realistic testing example demonstrating module-info-patch.maven for test-only module relationships

[ascheman]

Summary

Create a new example that demonstrates the legitimate use case for module-info-patch.maven in Maven 4: testing scenarios where test code needs module relationships (like JUnit dependencies or access to internal packages) that should not exist in production code.

Motivation

The existing example_addReads_addExports examples are somewhat unrealistic because they use --add-exports and --add-reads in main code. As Martin Desruisseaux (@desruisseaux) pointed out in PR #4, these options are necessary for tests but their use in main code is strongly discouraged.

Key insight from discussion: The legitimate use case is not about "lacking control over source code" but rather about test-specific requirements that should not be in production (e.g., JUnit dependencies, access to internal packages for testing).

Proposed Example Structure

Name: example_maven_module_patch_testing

Scenario: A multi-module Maven project where:

• Module under test (my.library): A library module with some internal (non-exported) packages
• Test module (my.library.tests): A separate Maven module containing tests that need:
  • Access to internal packages of my.library for whitebox testing
  • JUnit dependencies that should not appear in production module descriptor
  • Test utilities that require additional module reads

Maven Structure

example_maven_module_patch_testing/
├── pom.xml (parent aggregator)
├── library/
│   ├── pom.xml
│   └── src/
│       └── main/java/
│           └── module-info.java (production descriptor - minimal exports)
│           └── my/library/
│               ├── api/  (exported)
│               └── internal/  (NOT exported - but tests need access)
└── library-tests/
    ├── pom.xml (dependency on library module)
    └── src/
        └── test/java/
            └── module-info-patch.maven  (adds test-only relationships)
            └── my/library/tests/

Key Demonstrations

1. Test-only module relationships: module-info-patch.maven adds requires org.junit.jupiter.api only for tests
2. Access to internal packages: Use add-exports to access non-exported packages for whitebox testing
3. Transitive test dependencies: Show how test modules can patch their relationships without affecting production
4. Maven 4 best practices: Proper use of <scope>test</scope> with Module Source Hierarchy

Example module-info-patch.maven

patch-module my.library.tests {
    // Test framework dependency - NOT in production module-info.java
    requires org.junit.jupiter.api;
    requires org.junit.jupiter.params;
    
    // Access library's internal packages for whitebox testing
    add-reads my.library;
    
    // Open packages to JUnit for reflection-based testing
    opens my.library.tests to org.junit.platform.commons;
}

Benefits

• Realistic use case: Demonstrates why you'd actually use module-info-patch.maven in practice
• Best practices: Shows proper separation of test and production concerns
• Maven 4 features: Highlights the intended use of Module Source Hierarchy for tests
• Clear separation: Multi-module structure makes it obvious which code is test vs production
• Educational value: Explains when --add-exports is appropriate (testing) vs inappropriate (production)

Documentation Should Explain

• Why test-only module relationships are necessary
• How module-info-patch.maven keeps test concerns out of production descriptors
• The difference between this realistic scenario and the counter-example in example_addReads_addExports
• When to use whitebox vs blackbox testing approaches (cross-reference with example_test)

Related Examples

• example_test: Basic testing patterns (blackbox/whitebox)
• example_maven_test_blackbox: Maven-based blackbox testing
• example_maven_test_whitebox: Maven-based whitebox testing using --patch-module
• example_addReads_addExports: Counter-example showing what NOT to do in production code

---

This proposal addresses @desruisseaux's feedback and creates a practical, realistic example that showcases Maven 4's module-info-patch.maven feature in its intended context: testing.