Improve documentation for @IfProfileValue precedence [SPR-11902]

[spring-projects-issues]

Shalom Deitch opened SPR-11902 and commented

Status Quo

If you search for @IfProfileValue in the reference manual, you will find the following paragraph:

Indicates that the annotated test is enabled for a specific testing environment. If the configured ProfileValueSource returns a matching value for the provided name, the test is enabled. This annotation can be applied to an entire class or to individual methods. Class-level usage overrides method-level usage.

Proposal

If the class-level usage overrides the method-level, then there is no point in having both. I assume that it should be: method-level usage overrides class-level usage.

---

Affects: 4.0.5

Issue Links:

• Class-level @IfProfileValue overrides method-level @IfProfileValue settings [SPR-5902] #10571 Class-level @IfProfileValue overrides method-level @IfProfileValue settings
• ProfileValueUtils should enforce class-level usage of @IfProfileValue to override method-level usage [SPR-5914] #10583 ProfileValueUtils should enforce class-level usage of @IfProfileValue to override method-level usage

[spring-projects-issues]

Sam Brannen commented

Hi Shalom,

If the class-level usage overrides the method-level, then there is no point in having both. I assume that it should be: method-level usage overrides class-level usage.

The wording is perhaps a bit misleading but not completely incorrect. So please let me explain...

If a test class is disabled via @IfProfileValue, then the class-level configuration does in fact override whatever is declared at the method level.

In other words, the resulting boolean enabled value for the class level is effectively combined with the resulting boolean enabled value for the method level using AND semantics.

So a test is enabled if classLevel && methodLevel equates to boolean true. Otherwise, a test is disabled.

Keep in mind that the absence of @IfProfileValue is the same as true (i.e., enabled by default).

Does that make sense?

Cheers,

Sam

[spring-projects-issues]

Sam Brannen commented

Another way to think of @IfProfileValue is to compare it to the semantics associated with JUnit's @Ignore annotation.

If a test class is annotated with @Ignore, the entire test class (including all of its test methods) is ignored (i.e., disabled).

The same is true for @IfProfileValue, and that's why class-level usage of @IfProfileValue does in fact override method-level usage.

[spring-projects-issues]

Shalom Deitch commented

Sam - that last suggestion is good, it is a lot clearer - thanks

Maybe something in the line of:

@IfProfileValue defines if a test is enabled for a particular profile. The annotation can be on a whole class, individual methods, or both. If there is an annotation on both the class and the method, the test is enabled only if the profile name is a value in both annotations.
A profile is the value configured in a ProfileValueSource for the provided name.

For example in the below, the test method testProcessWhichRunsForUnitTestGroups will only be run for unit-tests.

@ContextConfiguration("/test-config.xml")
@IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"})
public class XmlApplicationContextTests {
   @IfProfileValue(name="test-groups", values={"unit-tests"})
   @Test
    public void testProcessWhichRunsForUnitTestGroups() {
          // some logic that should run only for unit  test groups
    }
}

Of course I am sure that you could word this better then I have, but since you have left me in the loop, this is my try. In any case, your last comment did make it clear to me.

thanks for everyone's efforts. I find Spring very impressive and most of it comes from being being aware and caring what the users think.

[spring-projects-issues]

Sam Brannen commented

Hi Shalom,

I'm glad to hear that I was able to clarify the behavior for you!

Thanks for the feedback! I'll take it into consideration when I update the documentation for Spring 4.1.

Regards,

Sam

[spring-projects-issues]

Sam Brannen commented

Completed in GitHub commit 3d95175.