From 361e6f3ed3a339c3eeea0449e4b8489c4f83490b Mon Sep 17 00:00:00 2001
From: Soby Chacko <soby.chacko@broadcom.com>
Date: Fri, 3 May 2024 16:03:49 -0400
Subject: [PATCH] GH-3225: Testing docs improvements

Fixes: #3225

* Clarify the usage of `@DirtiesContext` with `@EmbeddedKafka`
  when using `@SpringJunitConfig`.

* Addressing PR review
---
 .../main/antora/modules/ROOT/pages/testing.adoc    | 14 ++++++++++++--
 .../kafka/test/context/EmbeddedKafka.java          |  4 ++++
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/spring-kafka-docs/src/main/antora/modules/ROOT/pages/testing.adoc b/spring-kafka-docs/src/main/antora/modules/ROOT/pages/testing.adoc
index 0b387a9a..c4e37501 100644
--- a/spring-kafka-docs/src/main/antora/modules/ROOT/pages/testing.adoc
+++ b/spring-kafka-docs/src/main/antora/modules/ROOT/pages/testing.adoc
@@ -243,7 +243,7 @@ NOTE: `spring-kafka-test` has transitive dependencies on `junit-jupiter-api` and
 If you wish to use the embedded broker and are NOT using JUnit, you may wish to exclude these dependencies.
 
 [[embedded-kafka-annotation]]
-== @EmbeddedKafka Annotation
+== `@EmbeddedKafka` Annotation
 We generally recommend that you use the rule as a `@ClassRule` to avoid starting and stopping the broker between tests (and use a different topic for each test).
 Starting with version 2.0, if you use Spring's test application context caching, you can also declare a `EmbeddedKafkaBroker` bean, so a single broker can be used across multiple test classes.
 For convenience, we provide a test class-level annotation called `@EmbeddedKafka` to register the `EmbeddedKafkaBroker` bean.
@@ -317,7 +317,7 @@ Properties defined by `brokerProperties` override properties found in `brokerPro
 You can use the `@EmbeddedKafka` annotation with JUnit 4 or JUnit 5.
 
 [[embedded-kafka-junit5]]
-== @EmbeddedKafka Annotation with JUnit5
+== `@EmbeddedKafka` Annotation with JUnit5
 
 Starting with version 2.3, there are two ways to use the `@EmbeddedKafka` annotation with JUnit5.
 When used with the `@SpringJunitConfig` annotation, the embedded broker is added to the test application context.
@@ -404,6 +404,16 @@ public class MyApplicationTests {
 
 Notice that, since this is a Spring Boot application, we override the broker list property to set Spring Boot's property.
 
+[[embedded-broker-with-springjunitconfig-annotations]]
+== `@EmbeddedKafka` with `@SpringJunitConfig`
+
+When using `@EmbeddedKafka` with `@SpringJUnitConfig`, it is recommended to use `@DirtiesContext` on the test class.
+This is to prevent potential race conditions occurring during the JVM shutdown after running multiple tests in a test suite.
+For example, without using `@DirtiesContext`, the `EmbeddedKafkaBroker` may shutdown earlier while the application context still needs resources from it.
+Since every `EmbeddedKafka` test-runs create its own temporary directory, when this race condition occurs, it will produce error log messages indicating that the files that it is trying to delete or cleanup are not available anymore.
+Adding `@DirtiesContext` will ensure that the application context is cleaned up after each test and not cached, making it less vulnerable to potential resource race conditions like these.
+
+
 [[kafka-testing-embeddedkafka-annotation]]
 === `@EmbeddedKafka` Annotation or `EmbeddedKafkaBroker` Bean
 
diff --git a/spring-kafka-test/src/main/java/org/springframework/kafka/test/context/EmbeddedKafka.java b/spring-kafka-test/src/main/java/org/springframework/kafka/test/context/EmbeddedKafka.java
index c3ee14a2..f2b784c3 100644
--- a/spring-kafka-test/src/main/java/org/springframework/kafka/test/context/EmbeddedKafka.java
+++ b/spring-kafka-test/src/main/java/org/springframework/kafka/test/context/EmbeddedKafka.java
@@ -56,6 +56,10 @@ import org.springframework.test.context.aot.DisabledInAotMode;
  * }
  * </pre>
  *
+ * When using EmbeddedKafka with {@link org.springframework.test.context.junit.jupiter.SpringJUnitConfig},
+ * it is recommended to use {@link org.springframework.test.annotation.DirtiesContext} on the test class,
+ * in order to prevent certain race conditions on JVM shutdown when running multiple tests.
+ *
  * @author Artem Bilan
  * @author Elliot Metsger
  * @author Zach Olauson