Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation for @IfProfileValue precedence [SPR-11902] #16521

Closed
spring-issuemaster opened this issue Jun 24, 2014 · 5 comments
Closed

Improve documentation for @IfProfileValue precedence [SPR-11902] #16521

spring-issuemaster opened this issue Jun 24, 2014 · 5 comments
Assignees
Milestone

Comments

@spring-issuemaster
Copy link
Collaborator

@spring-issuemaster spring-issuemaster commented Jun 24, 2014

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:

  • #10571 Class-level @IfProfileValue overrides method-level @IfProfileValue settings
  • #10583 ProfileValueUtils should enforce class-level usage of @IfProfileValue to override method-level usage
@spring-issuemaster
Copy link
Collaborator Author

@spring-issuemaster spring-issuemaster commented Jun 25, 2014

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-issuemaster
Copy link
Collaborator Author

@spring-issuemaster spring-issuemaster commented Jun 25, 2014

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-issuemaster
Copy link
Collaborator Author

@spring-issuemaster spring-issuemaster commented Jun 26, 2014

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-issuemaster
Copy link
Collaborator Author

@spring-issuemaster spring-issuemaster commented Jun 26, 2014

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-issuemaster
Copy link
Collaborator Author

@spring-issuemaster spring-issuemaster commented Jul 9, 2015

Sam Brannen commented

Completed in GitHub commit 3d95175.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
You can’t perform that action at this time.