This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
commit 86578a47d91993997a455ac45b538106e64a0d40
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Wed Feb 21 10:59:43 2024 +0100
Documentation updates.
---
.../test/org/apache/sis/test/LoggingWatcher.java | 20 +++++++++++---------
.../test/org/apache/sis/test/TestStep.java | 12 +++++++-----
2 files changed, 18 insertions(+), 14 deletions(-)
diff --git
a/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/LoggingWatcher.java
b/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/LoggingWatcher.java
index c3d704e592..c3da1d85ad 100644
---
a/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/LoggingWatcher.java
+++
b/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/LoggingWatcher.java
@@ -47,15 +47,6 @@ import org.junit.jupiter.api.extension.ExtensionContext;
* }
* }
*
- * Recommended but not mandatory, ensure that there is no unexpected logging
in any tests:
- *
- * {@snippet lang="java" :
- * @AfterEach
- * public void assertNoUnexpectedLog() {
- * loggings.assertNoUnexpectedLog();
- * }
- * }
- *
* In tests that are expected to emit warnings, add the following lines:
*
* {@snippet lang="java" :
@@ -64,6 +55,17 @@ import org.junit.jupiter.api.extension.ExtensionContext;
* loggings.assertNoUnexpectedLog();
* }
*
+ * Callers should invoke {@link #assertNoUnexpectedLog()} at the end of each
test method.
+ * Alternatively, the check can also be done automatically as below (but the
stack trace
+ * may be more confusing):
+ *
+ * {@snippet lang="java" :
+ * @AfterEach
+ * public void assertNoUnexpectedLog() {
+ * loggings.assertNoUnexpectedLog();
+ * }
+ * }
+ *
* <h2>Multi-threading</h2>
* By default, {@code LoggingWatcher} handles only the log records emitted by
the same thread as the one
* that constructed this watcher. If tests are running in parallel, log
records emitted by other threads
diff --git
a/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/TestStep.java
b/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/TestStep.java
index c678d1a7e4..f6f39fbca1 100644
--- a/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/TestStep.java
+++ b/endorsed/src/org.apache.sis.util/test/org/apache/sis/test/TestStep.java
@@ -25,12 +25,14 @@ import java.lang.annotation.RetentionPolicy;
/**
* A test method producing an object to be used by another test method.
+ * This annotation is for documentation purpose only. It is used in
replacement to
+ * {@link org.junit.jupiter.api.Test} when the method is invoked by another
method.
+ * It may be because the methods need to be invoked inside a {@code try …
finally}
+ * block, or because the result of a test is used by a next step.
*
- * <p>If this annotation was supported, we would annotate some methods with
the {@code TestStep} annotation
- * instead of the JUnit {@link org.junit.jupiter.api.Test} one. However, in
current implementation, this functionality
- * is not supported and the test step methods must be explicitly invoked from
another method. Consequently
- * this annotation is currently used only for documentation purpose, in case a
future JUnit version would
- * support tests chaining.</p>
+ * <p>We currently do not use {@link org.junit.jupiter.api.TestMethodOrder}
annotation for
+ * the purposes described above because the semantic during parallel execution
is unclear,
+ * and we do not want to force {@code Lifecycle.PER_CLASS} on those tests.</p>
*
* @author Martin Desruisseaux (Geomatys)
*/
