- * Test annotation to indicate that a test is enabled for a specific testing - * profile or environment. If the configured {@link ProfileValueSource} returns - * a matching {@link #value} for the provided {@link #name}, the test will be - * enabled. - *
- *- * Note: {@code @IfProfileValue} can be applied at the class level, the method - * level, or both. {@code @IfProfileValue} at the class level overrides - * method-level usage of {@code @IfProfileValue} for any methods within that - * class. - *
+ * Test annotation to indicate whether a test is enabled or disabled for a + * specific testing profile. + * + *In the context of this annotation, the term profile refers to + * a Java system property by default; however, the semantics can be changed + * by implementing a custom {@link ProfileValueSource}. If the configured + * {@code ProfileValueSource} returns a matching {@link #value} for the + * declared {@link #name}, the test will be enabled. Otherwise, the test + * will be disabled and effectively ignored. + * + *
{@code @IfProfileValue} can be applied at the class level, the method + * level, or both. Class-level usage of {@code @IfProfileValue} takes + * precedence over method-level usage for any methods within that class or + * its subclasses. Specifically, a test is enabled if it is enabled both at + * the class level and at the method level; the absence of + * {@code @IfProfileValue} means the test is implicitly enabled. This is + * analogous to the semantics of JUnit's {@link org.junit.Ignore @Ignore} + * annotation, except that the presence of {@code @Ignore} always disables + * a test. + * + *
- * When using {@link SystemProfileValueSource} as the {@link ProfileValueSource} - * implementation, you can configure a test method to run only on Java VMs from - * Sun Microsystems as follows: - *
*
- * @IfProfileValue(name = "java.vendor", value = "Sun Microsystems Inc.")
+ * @IfProfileValue(name = "java.vendor", value = "Oracle Corporation")
* public void testSomething() {
- * // ...
- * }
- *
- * - * You can alternatively configure {@code @IfProfileValue} with OR - * semantics for multiple {@link #values() values} as follows (assuming a - * {@link ProfileValueSource} has been appropriately configured for the - * "test-groups" name): - *
+ * // ... + * } + * + *You can alternatively configure {@code @IfProfileValue} with OR + * semantics for multiple {@link #values}. The following test will be enabled + * if a {@code ProfileValueSource} has been appropriately configured for the + * {@code "test-groups"} profile with a value of either {@code unit-tests} + * or {@code integration-tests}. This functionality is similar to + * TestNG's support for test groups and JUnit's experimental support + * for test categories. * *
* @IfProfileValue(name = "test-groups", values = { "unit-tests", "integration-tests" })
* public void testWhichRunsForUnitOrIntegrationTestGroups() {
- * // ...
- * }
- *
+ * // ...
+ * }
*
+ * Although the {@code @IfProfileValue} and + * {@link org.springframework.context.annotation.Profile @Profile} annotations + * both involve profiles, they are not directly related. {@code @Profile} + * involves bean definition profiles configured in the + * {@link org.springframework.core.env.Environment Environment}; whereas, + * {@code @IfProfileValue} is used to enable or disable tests. + * + *
As of Spring Framework 4.0, this annotation may be used as a * meta-annotation to create custom composed annotations. * @@ -70,37 +86,40 @@ import java.lang.annotation.Target; * @author Sam Brannen * @since 2.0 * @see ProfileValueSource + * @see SystemProfileValueSource * @see ProfileValueSourceConfiguration * @see ProfileValueUtils * @see org.springframework.test.context.junit4.AbstractJUnit4SpringContextTests * @see org.springframework.test.context.junit4.SpringJUnit4ClassRunner + * @see org.springframework.test.context.junit4.statements.ProfileValueChecker + * @see org.springframework.context.annotation.Profile + * @see org.springframework.test.context.ActiveProfiles */ @Documented @Inherited @Retention(RetentionPolicy.RUNTIME) -@Target( { ElementType.TYPE, ElementType.METHOD }) +@Target({ ElementType.TYPE, ElementType.METHOD }) public @interface IfProfileValue { /** - * The {@code name} of the profile value against which to - * test. + * The {@code name} of the profile value against which to test. */ String name(); /** * A single, permissible {@code value} of the profile value - * for the given {@link #name() name}. - *
- * Note: Assigning values to both {@link #value()} and {@link #values()} + * for the given {@link #name}. + * + *
Note: Assigning values to both {@link #value} and {@link #values} * will lead to a configuration conflict. */ String value() default ""; /** - * A list of all permissible {@code values} of the - * profile value for the given {@link #name() name}. - *
- * Note: Assigning values to both {@link #value()} and {@link #values()} + * A list of all permissible {@code values} of the profile value + * for the given {@link #name}. + * + *
Note: Assigning values to both {@link #value} and {@link #values} * will lead to a configuration conflict. */ String[] values() default {}; diff --git a/src/asciidoc/testing.adoc b/src/asciidoc/testing.adoc index 9d6dc1ea33..b9b2f14e7a 100644 --- a/src/asciidoc/testing.adoc +++ b/src/asciidoc/testing.adoc @@ -991,8 +991,15 @@ The following annotations are __only__ supported when used in conjunction with t 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. +test is enabled. Otherwise, the test will be disabled and effectively _ignored_. + +`@IfProfileValue` can be applied at the class level, the method level, or both. +Class-level usage of `@IfProfileValue` takes precedence over method-level usage for any +methods within that class or its subclasses. Specifically, a test is enabled if it is +enabled both at the class level _and_ at the method level; the absence of +`@IfProfileValue` means the test is implicitly enabled. This is analogous to the +semantics of JUnit's `@Ignore` annotation, except that the presence of `@Ignore` always +disables a test. +