Polish System Properties extension support and documentation

Author: sbrannen

documentation/modules/ROOT/pages/writing-tests/built-in-extensions.adoc

@@ -296,23 +296,24 @@ respective annotations.
 Tests annotated with one of the above annotations will never execute in parallel with
 tests annotated with `@DefaultLocale` or `@DefaultTimeZone`.
 
-[[SystemProperties]]
-== The System Property Extensions
+[[system-properties]]
+== The System Properties Extension
 
-The system property extensions provide a set of annotations that work together to clear,
-set, and restore system properties.
+The system properties extension supports a set of annotations that work together to clear,
+set, and restore JVM system properties.
 
-[[SystemProperties-clear-and-set]]
+[[system-properties-clear-and-set]]
 === @ClearSystemProperty and @SetSystemProperty
 
-The `{ClearSystemProperty}` and `{SetSystemProperty}` annotations can be used to clear
-and set, respectively, the values of system properties for test execution. Both
+The `{ClearSystemProperty}` and `{SetSystemProperty}` annotations can be used to clear and
+set, respectively, the values of JVM system properties for test execution. Both
 annotations work on the test method and class level and are repeatable, combinable, and
 inherited from higher-level containers. After the annotated method has been executed, the
 properties configured in the annotation will be restored to their original value or the
 value of the higher-level container, or will be cleared if they did not previously have a
-value. Other system properties that are changed during the test are _not_ restored
-(unless <<SystemProperties-restore, explicitly enabled>> via `{RestoreSystemProperties}`).
+value. Other system properties that are changed during the test are _not_ restored (unless
+restoration is <<system-properties-restore, explicitly enabled>> via
+`{RestoreSystemProperties}`).
 
 For example, clearing a system property for test execution can be done as follows.
 
@@ -354,7 +355,7 @@ With class-level configuration, the specified system properties are cleared or s
 and reset after each individual test in the annotated class.
 ====
 
-[[SystemProperties-restore]]
+[[system-properties-restore]]
 === @RestoreSystemProperties
 
 The `{RestoreSystemProperties}` annotation can be used to restore changes to system
@@ -400,7 +401,7 @@ property changes made within the annotated class are completely restored after t
 lifecycle, ensuring that changes are not visible to `SomeOtherTestClass`. Note that
 `SomeOtherTestClass` uses the `@ReadsSystemProperty` annotation, which ensures that JUnit
 does not schedule the class to run during any test known to modify system properties (see
-<<SystemProperties-thread-safety>>).
+<<system-properties-thread-safety>>).
 
 [source,java,indent=0]
 ----
@@ -414,7 +415,7 @@ Some other test class, running later:
 include::example$java/example/SystemPropertyExtensionDemo.java[tag=systemproperty_class_restore_isolated_class]
 ----
 
-[[SystemProperties-combined-usage]]
+[[system-properties-combined-usage]]
 === Combining @ClearSystemProperty, @SetSystemProperty, and @RestoreSystemProperties
 
 The three system property annotations can be combined, which can be useful when some
@@ -436,7 +437,7 @@ the referenced properties. `@RestoreSystemProperties` is only needed if system p
 are modified during a test in some way _other than_ via the `Clear` and `Set` annotations.
 ====
 
-[[SystemProperties-thread-safety]]
+[[system-properties-thread-safety]]
 === Thread Safety
 
 Since system properties are global state, reading and writing them during

junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ClearSystemProperty.java

@@ -23,45 +23,53 @@
 import org.junit.jupiter.api.extension.ExtendWith;
 
 /**
- * {@code @ClearSystemProperty} is a JUnit Jupiter extension to clear the value
- * of a system property for a test execution.
+ * {@code @ClearSystemProperty} is an annotation that is used to clear the value
+ * of a JVM system property for test execution.
  *
- * <p>The key of the system property to be cleared must be specified via {@link #key()}.
- * After the annotated element has been executed, the original value or the value of the
- * higher-level container is restored.</p>
+ * <p>The key of the system property must be specified via the {@link #key() key}
+ * attribute.
  *
  * <p>{@code @ClearSystemProperty} can be used on the method and on the class level.
- * It is repeatable and inherited from higher-level containers. If a class is
- * annotated, the configured property will be cleared before every test inside that
- * class.</p>
+ * It is {@linkplain Repeatable repeatable} and {@link Inherited @Inherited} from
+ * higher-level containers. If a class is annotated, the configured property will
+ * be cleared before every test inside that class.  After a test has completed,
+ * the original value of the system property will be restored.
  *
- * <p>During
- * <a href="https://docs.junit.org/current/writing-tests/parallel-execution.html">parallel test execution</a>,
- * all tests annotated with {@link ClearSystemProperty}, {@link SetSystemProperty}, {@link ReadsSystemProperty}, and {@link WritesSystemProperty}
- * are scheduled in a way that guarantees correctness under mutation of shared global state.</p>
+ * <p>During <a href="https://docs.junit.org/current/writing-tests/parallel-execution.html">
+ * parallel test execution</a>, all tests annotated with
+ * {@link SetSystemProperty @SetSystemProperty},
+ * {@link ClearSystemProperty @ClearSystemProperty},
+ * {@link ReadsSystemProperty @ReadsSystemProperty}, and
+ * {@link WritesSystemProperty @WritesSystemProperty} are scheduled in a way that
+ * guarantees correctness under mutation of shared global state.
  *
- * <p>For more details and examples, see
- * <a href="https://docs.junit.org/current/writing-tests/built-in-extensions.html#SystemProperty">the documentation on <code>@ClearSystemProperty and @SetSystemProperty</code></a>.</p>
+ * <p>For further details and examples, see the documentation on all JVM system
+ * property annotations in the
+ * <a href="https://docs.junit.org/current/writing-tests/built-in-extensions.html#system-properties">
+ * User Guide</a>.
  *
  * @since 6.1
+ * @see SetSystemProperty @SetSystemProperty
+ * @see RestoreSystemProperties @RestoreSystemProperties
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.TYPE })
 @Inherited
 @Repeatable(ClearSystemProperty.ClearSystemProperties.class)
 @WritesSystemProperty
-@ExtendWith(SystemPropertyExtension.class)
+@ExtendWith(SystemPropertiesExtension.class)
 @API(status = EXPERIMENTAL, since = "6.1")
 @SuppressWarnings("exports")
 public @interface ClearSystemProperty {
 
 	/**
-	 * The key of the system property to be cleared.
+	 * The key of the system property to clear.
 	 */
 	String key();
 
 	/**
-	 * Containing annotation of repeatable {@code @ClearSystemProperty}.
+	 * {@code @ClearSystemProperties} is a container for one or more
+	 * {@code ClearSystemProperty} declarations.
 	 */
 	@Retention(RetentionPolicy.RUNTIME)
 	@Target({ ElementType.METHOD, ElementType.TYPE })
@@ -70,6 +78,10 @@
 	@API(status = EXPERIMENTAL, since = "6.1")
 	@interface ClearSystemProperties {
 
+		/**
+		 * An array of one or more {@link ClearSystemProperty @ClearSystemProperty}
+		 * declarations.
+		 */
 		ClearSystemProperty[] value();
 
 	}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/JupiterPropertyUtils.java

@@ -38,13 +38,12 @@ private static void throwIfHasObservableDefaults(ExtensionContext context, Prope
 				.filter(propertyName -> !keySet.contains(propertyName)) //
 				.toList();
 		if (!defaultPropertyNames.isEmpty()) {
-			throw new ExtensionConfigurationException(
-				("SystemPropertyExtension was configured to restore the system properties by [%s]. " //
-						+ "It was not possible to create an accurate snapshot of the system properties using Properties::clone because default properties [%s] were present." //
-				).formatted( //
-					context.getElement().orElseThrow(), //
-					String.join(", ", defaultPropertyNames) //
-				));
+			throw new ExtensionConfigurationException("""
+					SystemPropertiesExtension was configured to restore the system properties by [%s]. \
+					However, it was not possible to create an accurate snapshot of the system properties \
+					using Properties::clone, because default properties were present: %s""" //
+					.formatted(context.getElement().orElseThrow(), defaultPropertyNames));
 		}
 	}
+
 }

junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/ReadsSystemProperty.java

@@ -24,17 +24,24 @@
 import org.junit.jupiter.api.parallel.Resources;
 
 /**
- * Marks tests that read system properties but don't use the system property extension themselves.
+ * {@code @ReadsSystemProperty} marks tests that read system properties but do
+ * not use the JVM system properties extensions themselves.
  *
- * <p>During
- * <a href="https://docs.junit.org/current/writing-tests/parallel-execution.html">parallel test execution</a>,
- * all tests annotated with {@link ClearSystemProperty}, {@link SetSystemProperty}, {@link ReadsSystemProperty}, and {@link WritesSystemProperty}
- * are scheduled in a way that guarantees correctness under mutation of shared global state.</p>
+ * <p>During <a href="https://docs.junit.org/current/writing-tests/parallel-execution.html">
+ * parallel test execution</a>, all tests annotated with
+ * {@link SetSystemProperty @SetSystemProperty},
+ * {@link ClearSystemProperty @ClearSystemProperty},
+ * {@link ReadsSystemProperty @ReadsSystemProperty}, and
+ * {@link WritesSystemProperty @WritesSystemProperty} are scheduled in a way that
+ * guarantees correctness under mutation of shared global state.
  *
- * <p>For more details and examples, see
- * <a href="https://docs.junit.org/current/writing-tests/built-in-extensions.html#SystemProperty">the documentation on <code>@ClearSystemProperty</code> and <code>@SetSystemProperty</code></a>.</p>
+ * <p>For further details and examples, see the documentation on all JVM system
+ * property annotations in the
+ * <a href="https://docs.junit.org/current/writing-tests/built-in-extensions.html#system-properties">
+ * User Guide</a>.
  *
  * @since 6.1
+ * @see WritesSystemProperty @WritesSystemProperty
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PACKAGE, ElementType.TYPE })

junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/RestoreSystemProperties.java

@@ -23,52 +23,64 @@
 import org.junit.jupiter.api.extension.ExtendWith;
 
 /**
- * {@code @RestoreSystemProperties} is a JUnit Jupiter extension to restore the entire set of
- * system properties to the original value, or the value of the higher-level container, after the
- * annotated element is complete.
+ * {@code @RestoreSystemProperties} is an annotation that is used to restore the
+ * entire set of JVM system properties to its original state, or the state of the
+ * higher-level container, after execution of the annotated element has completed.
  *
- * <p>Use this annotation when there is a need programmatically modify system properties in a test
- * method or in {@code @BeforeAll} / {@code @BeforeEach} blocks.
- * To set or clear a system property, consider {@link SetSystemProperty @SetSystemProperty} or
+ * <p>Use this annotation when there is a need to programmatically modify system
+ * properties in a test method or in {@code @BeforeAll} / {@code @BeforeEach}
+ * lifecycle methods. To set or clear a system property, consider
+ * {@link SetSystemProperty @SetSystemProperty} or
  * {@link ClearSystemProperty @ClearSystemProperty} instead.
  *
- * <p>{@code @RestoreSystemProperties} can be used on the method and on the class level.
- * When placed on a test method, a snapshot of system properties is stored prior to that test.
- * The snapshot is created before any {@code @BeforeEach} blocks in scope and before any
- * {@link SetSystemProperty @SetSystemProperty} or {@link ClearSystemProperty @ClearSystemProperty}
- * annotations on that method. After the test, system properties are restored from the
- * snapshot after any {@code @AfterEach} have completed.
+ * <p>{@code @RestoreSystemProperties} can be used on the method and on the class
+ * level.
  *
- * <p>When placed on a test class, a snapshot of system properties is stored prior to any
- * {@code @BeforeAll} blocks in scope and before any {@link SetSystemProperty @SetSystemProperty}
- * or {@link ClearSystemProperty @ClearSystemProperty} annotations on that class.
- * After the test class completes, system properties are restored from the snapshot after any
- * {@code @AfterAll} blocks have completed.
- * In addition, a class level annotation is inherited by each test method just as if each one was
+ * <p>When declared on a test method, a snapshot of all JVM system properties is
+ * stored prior to that test. The snapshot is created before any {@code @BeforeEach}
+ * lifecycle methods in scope and before any {@link SetSystemProperty @SetSystemProperty}
+ * or {@link ClearSystemProperty @ClearSystemProperty} annotations on that method.
+ * After the test, system properties are restored from the snapshot after all
+ * {@code @AfterEach} lifecycle methods have completed.
+ *
+ * <p>When placed on a test class, a snapshot of all JVM system properties is stored
+ * prior to any {@code @BeforeAll} lifecycle methods in scope and before any
+ * {@link SetSystemProperty @SetSystemProperty} or
+ * {@link ClearSystemProperty @ClearSystemProperty} annotations on that class.
+ * After the test class completes, system properties are restored from the snapshot
+ * after any {@code @AfterAll} lifecycle methods have completed. In addition, a
+ * class-level annotation is inherited by each test method just as if each one were
  * annotated with {@code RestoreSystemProperties}.
  *
- * <p>During
- * <a href="https://docs.junit.org/current/writing-tests/parallel-execution.html">parallel test execution</a>,
- * all tests annotated with {@link RestoreSystemProperties}, {@link SetSystemProperty},
- * {@link ReadsSystemProperty}, and {@link WritesSystemProperty}
- * are scheduled in a way that guarantees correctness under mutation of shared global state.
+ * <p>During <a href="https://docs.junit.org/current/writing-tests/parallel-execution.html">
+ * parallel test execution</a>, all tests annotated with
+ * {@link SetSystemProperty @SetSystemProperty},
+ * {@link ClearSystemProperty @ClearSystemProperty},
+ * {@link ReadsSystemProperty @ReadsSystemProperty}, and
+ * {@link WritesSystemProperty @WritesSystemProperty} are scheduled in a way that
+ * guarantees correctness under mutation of shared global state.
  *
- * <p>For more details and examples, see
- * <a href="https://docs.junit.org/current/writing-tests/built-in-extensions.html#SystemProperty">the documentation on
- * <code>@ClearSystemProperty</code>, <code>@SetSystemProperty</code>, and <code>@RestoreSystemProperties</code></a>.</p>
+ * <p>For further details and examples, see the documentation on all JVM system
+ * property annotations in the
+ * <a href="https://docs.junit.org/current/writing-tests/built-in-extensions.html#system-properties">
+ * User Guide</a>.
  *
- * <p><em>Note:</em> The snapshot of the properties object is created using {@link Properties#clone()}.
- * This cloned value will not include any default values. This extension will make a best effort
- * attempt to detect default values and fail if any are detected. For classes that extend
- * {@code Properties}, it is assumed that {@code clone()} is implemented with sufficient fidelity.
+ * <p><em>Note:</em> The snapshot of the properties object is created using
+ * {@link Properties#clone()}. However, this cloned properties object will not
+ * include any default values from the original properties object. Consequently,
+ * this extension will make a best effort attempt to detect default values and
+ * fail if any are detected. For classes that extend {@code Properties}, it is
+ * assumed that {@code clone()} is implemented with sufficient fidelity.
  *
  * @since 6.1
+ * @see ClearSystemProperty @ClearSystemProperty
+ * @see SetSystemProperty @SetSystemProperty
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.TYPE })
 @Inherited
 @WritesSystemProperty
-@ExtendWith(SystemPropertyExtension.class)
+@ExtendWith(SystemPropertiesExtension.class)
 @API(status = EXPERIMENTAL, since = "6.1")
 @SuppressWarnings("exports")
 public @interface RestoreSystemProperties {