From af977c08919afbf31b9bd9942167bcb75ec8680e Mon Sep 17 00:00:00 2001
From: Sam Brannen <sbrannen@vmware.com>
Date: Thu, 10 Mar 2022 19:27:41 +0100
Subject: [PATCH] Improve documentation for @EnabledIf and @DisabledIf test
 support

Closes gh-28157
---
 .../context/junit/jupiter/DisabledIf.java     | 13 +++++++++-
 .../test/context/junit/jupiter/EnabledIf.java | 13 +++++++++-
 src/docs/asciidoc/testing.adoc                | 26 +++++++++++++++++++
 3 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/DisabledIf.java b/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/DisabledIf.java
index 139d16257495..02223b656643 100644
--- a/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/DisabledIf.java
+++ b/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/DisabledIf.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -50,12 +50,23 @@
  * public {@literal @}interface DisabledOnMac {}
  * </pre>
  *
+ * <p>Please note that {@code @DisabledOnMac} is meant only as an example of what
+ * is possible. If you have that exact use case, please use the built-in
+ * {@link org.junit.jupiter.api.condition.DisabledOnOs @DisabledOnOs(MAC)} support
+ * in JUnit Jupiter.
+ *
+ * <p>Since JUnit 5.7, JUnit Jupiter also has a condition annotation named
+ * {@link org.junit.jupiter.api.condition.DisabledIf @DisabledIf}. Thus, if you
+ * wish to use Spring's {@code @DisabledIf} support make sure you import the
+ * annotation type from the correct package.
+ *
  * @author Sam Brannen
  * @author Tadaya Tsuyukubo
  * @since 5.0
  * @see SpringExtension
  * @see EnabledIf
  * @see org.junit.jupiter.api.Disabled
+ * @see org.junit.jupiter.api.condition.DisabledIf
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/EnabledIf.java b/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/EnabledIf.java
index c1fd3bbaf12f..a80f2cef8095 100644
--- a/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/EnabledIf.java
+++ b/spring-test/src/main/java/org/springframework/test/context/junit/jupiter/EnabledIf.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -50,11 +50,22 @@
  * public {@literal @}interface EnabledOnMac {}
  * </pre>
  *
+ * <p>Please note that {@code @EnabledOnMac} is meant only as an example of what
+ * is possible. If you have that exact use case, please use the built-in
+ * {@link org.junit.jupiter.api.condition.EnabledOnOs @EnabledOnOs(MAC)} support
+ * in JUnit Jupiter.
+ *
+ * <p>Since JUnit 5.7, JUnit Jupiter also has a condition annotation named
+ * {@link org.junit.jupiter.api.condition.EnabledIf @EnabledIf}. Thus, if you
+ * wish to use Spring's {@code @EnabledIf} support make sure you import the
+ * annotation type from the correct package.
+ *
  * @author Sam Brannen
  * @since 5.0
  * @see SpringExtension
  * @see DisabledIf
  * @see org.junit.jupiter.api.Disabled
+ * @see org.junit.jupiter.api.condition.EnabledIf
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc
index f7f2dfe9a116..9a3dbf598e98 100644
--- a/src/docs/asciidoc/testing.adoc
+++ b/src/docs/asciidoc/testing.adoc
@@ -1960,6 +1960,19 @@ example, you can create a custom `@EnabledOnMac` annotation as follows:
 	annotation class EnabledOnMac {}
 ----
 
+[NOTE]
+====
+`@EnabledOnMac` is meant only as an example of what is possible. If you have that exact
+use case, please use the built-in `@EnabledOnOs(MAC)` support in JUnit Jupiter.
+====
+
+[WARNING]
+====
+Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@EnabledIf`. Thus,
+if you wish to use Spring's `@EnabledIf` support make sure you import the annotation type
+from the correct package.
+====
+
 [[integration-testing-annotations-junit-jupiter-disabledif]]
 ===== `@DisabledIf`
 
@@ -2008,6 +2021,19 @@ example, you can create a custom `@DisabledOnMac` annotation as follows:
 	annotation class DisabledOnMac {}
 ----
 
+[NOTE]
+====
+`@DisabledOnMac` is meant only as an example of what is possible. If you have that exact
+use case, please use the built-in `@DisabledOnOs(MAC)` support in JUnit Jupiter.
+====
+
+[WARNING]
+====
+Since JUnit 5.7, JUnit Jupiter also has a condition annotation named `@DisabledIf`. Thus,
+if you wish to use Spring's `@DisabledIf` support make sure you import the annotation type
+from the correct package.
+====
+
 [[integration-testing-annotations-meta]]
 ==== Meta-Annotation Support for Testing