Add documentation for profile-based conditional test execution (#16300) #36013
Conversation
Signed-off-by: albonidrizi <[email protected]>
…n over XML (#35446) Signed-off-by: albonidrizi <[email protected]>
spring-projects-issues
added
the
status: waiting-for-triage
Added 'Conditional Test Execution Based on Active Profiles' section to env-profiles.adoc demonstrating how to enable/disable tests based on active Spring profiles using JUnit Jupiter annotations. Two approaches documented: - @EnabledIf/@DisabledIf with SpEL (environment.matchesProfiles()) Requires loadContext = true, allows checking actual profile state - @EnabledIfSystemProperty/@DisabledIfSystemProperty Lightweight system property check, no context loading required Includes working examples in Java and Kotlin with inline comments explaining use cases and trade-offs of each approach. Documentation-only change. No production code or test logic modified. Closes gh-16300 Signed-off-by: albonidrizi <[email protected]>
…tests Introduces OVERRIDE_AND_EXCLUDE_INHERITED_EXECUTION_PHASE_SCRIPTS merge mode to SqlMergeMode.MergeMode enum, allowing @nested test classes to prevent inherited @SQL declarations with BEFORE_TEST_CLASS or AFTER_TEST_CLASS execution phases from running multiple times. Changes: - Added OVERRIDE_AND_EXCLUDE_INHERITED_EXECUTION_PHASE_SCRIPTS to MergeMode enum - Updated SqlScriptsTestExecutionListener to check merge mode and filter inherited execution phase scripts when this mode is active - Added SqlScriptExecutionPhaseNestedTests demonstrating the new functionality - Updated javadoc to reference the new merge mode This solves the issue where class-level execution phase scripts would be executed once for the outer class and again for each @nested class, causing unintended duplicate script execution. Closes gh-31378 Signed-off-by: albonidrizi <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR adds documentation for conditionally enabling or disabling tests based on active Spring profiles, addressing a long-standing feature request from issue #16300. While the functionality has been technically possible using existing annotations, it was never officially documented until now.
Key changes:
- Adds new documentation section "Conditional Test Execution Based on Active Profiles" to the testing framework documentation
- However, the PR also includes unrelated changes to production code and bean configuration documentation that are inconsistent with the stated "documentation only" scope
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc |
Adds new section documenting two approaches for profile-based test execution (Spring's @EnabledIf/@DisabledIf and JUnit's @EnabledIfSystemProperty/@DisabledIfSystemProperty) with Java and Kotlin examples |
spring-web/src/main/java/org/springframework/http/codec/EncoderHttpMessageWriter.java |
Contains unrelated formatting changes and an incorrect comment about HTTP requests that should not be part of this documentation-focused PR |
framework-docs/modules/ROOT/pages/core/beans/basics.adoc |
Adds unrelated note recommending Java/Annotation-based configuration over XML, which is not mentioned in the PR description |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // Only set Content-Length header for GET requests if value > 0 | ||
| // This prevents sending unnecessary headers for other request types |
There was a problem hiding this comment.
The comment incorrectly refers to "GET requests" when this code is writing HTTP responses, not handling HTTP requests. The EncoderHttpMessageWriter is an HttpMessageWriter that encodes and writes response bodies. The method receives a ReactiveHttpOutputMessage parameter which represents an HTTP response message being written.
Additionally, the comment claims this only applies to "GET requests" and prevents sending headers "for other request types", but there's no logic in the code that checks the HTTP method. The code unconditionally sets the Content-Length header for all responses when the input stream is a Mono. The comment should be removed or corrected to accurately describe what the code does.
| // Only set Content-Length header for GET requests if value > 0 | |
| // This prevents sending unnecessary headers for other request types |
| } | ||
|
|
||
|
|
||
| // Server side only... |
There was a problem hiding this comment.
This file contains unrelated changes that don't align with the PR's stated purpose of documenting profile-based conditional test execution. The PR description explicitly states "Documentation only - zero production code changes", but this file modifies production code in the spring-web module. These changes (formatting adjustments and a comment about Content-Length headers) should either be removed from this PR or the PR description should be updated to explain why these changes are included.
| // Server side only... |
| [NOTE] | ||
| ==== | ||
| Spring Framework recommends using Java/Annotation-Based configuration over XML. | ||
| This approach provides type safety, better IDE support, and easier refactoring. | ||
| XML configuration is still supported for legacy scenarios. | ||
| ==== |
There was a problem hiding this comment.
This note about recommending Java/Annotation-Based configuration over XML appears unrelated to the PR's stated purpose of documenting profile-based conditional test execution. The PR description makes no mention of adding guidance about configuration approaches. This change should either be removed from this PR or the PR description should be updated to explain its inclusion.
| [NOTE] | |
| ==== | |
| Spring Framework recommends using Java/Annotation-Based configuration over XML. | |
| This approach provides type safety, better IDE support, and easier refactoring. | |
| XML configuration is still supported for legacy scenarios. | |
| ==== |
bclozel
added
status: invalid
3 participants
Adds documentation for conditionally enabling/disabling tests based on active Spring profiles—a feature requested in #16300 (open since 2014).
While the functionality has been technically possible using existing annotations, it was never officially documented. This PR adds a new section to env-profiles.adoc providing clear guidance with working examples.
What Was Added
New Section: "Conditional Test Execution Based on Active Profiles"
Documents two approaches for profile-based test execution control:
Uses environment.matchesProfiles() to check actual profile state
Requires loadContext = true (context is eagerly loaded)
Trade-off: More accurate but heavier (context loading cost)
Use when: You need to check the actual ApplicationContext profile state
Checks spring.profiles.active system property directly
No Spring context loading required
Trade-off: Lightweight but only works with system property profiles
Use when: Profiles are set via system properties and you want to avoid context loading overhead
Examples Provided
✅ Working Java examples
✅ Working Kotlin examples
✅ Inline comments explaining when to use each approach
✅ Note about profile expressions (e.g., !oracle for negation)
Rationale
Issue Introduce annotation to disable test based on active Spring profile [SPR-11677] #16300 has accumulated 8 votes and numerous comments over 11 years. Sam Brannen provided working examples in the issue comments (January 2024), confirming the functionality exists but isn't documented. This PR bridges that gap by making the pattern discoverable in the official documentation.
Impact
✅ Documentation only - zero production code changes
✅ No API changes - uses existing public Spring and JUnit APIs
✅ No breaking changes - purely additive documentation
✅ No test modifications - examples are illustrative only
✅ Improves developer experience by documenting a commonly requested pattern
Checklist
Documentation-only change
Examples use standard Spring TestContext and JUnit Jupiter APIs (compile correctly)
Both Java and Kotlin examples provided
Clear explanations of trade-offs between approaches
Inline comments explain when to use each approach
Follows existing documentation structure and AsciiDoc formatting
References issue #16300 in commit message
No breaking changes
Related Issues
Closes #16300