Add documentation

docs/docs-nav.yml

@@ -21,6 +21,8 @@
         url: /docs/disable-parameterized-tests/
       - title: "Expected-to-Fail Tests"
         url: /docs/expected-to-fail-tests/
+      - title: "Fail Test at a Date"
+        url: /docs/fail-at/
       - title: "Injecting Resources"
         url: /docs/resources/
       - title: "Injecting Temporary Directories"

docs/fail-at.adoc

@@ -0,0 +1,56 @@
+:page-title: Fail test after certain date
+:page-description: The JUnit 5 (Jupiter) extension `@FailAt` fails a test after a certain date
+:xp-demo-dir: ../src/demo/java
+:demo: {xp-demo-dir}/org/junitpioneer/jupiter/FailAtExtensionDemo.java
+
+It's sometimes useful to fail a test after a certain date.
+One can imagine many reasons for doing so, maybe a remote dependency of the test is not licenced anymore.
+
+The `@FailAt` annotation is perfectly adequate to use in such cases.
+The test will fail when the given date is reached.
+
+[WARNING]
+====
+This annotation allows the user to move an https://junit.org/junit5/docs/current/user-guide/#writing-tests-assumptions[assumption] out of one or multiple test method's code into the annotation.
+But this comes at a cost - applying `@FailAt` can make the test suite non-reproducible.
+If a passing test is run again after the "failAt" date that build would fail.
+A report entry is issued for every test that does not fail until a certain date.
+====
+
+== Usage
+
+To mark a test to fail at a given date add the `@FailAt` annotation like so:
+
+[source,java,indent=0]
+----
+include::{demo}[tag=fail_at_simple]
+----
+
+The `date` parameter must be a string in the date format specified by https://en.m.wikipedia.org/wiki/ISO_8601[ISO 8601], e.g. "1985-10-26".
+Invalid or unparsable date strings lead to an `ExtensionConfigurationException`.
+
+The `@FailAt annotation may optionally be declared with a reason to document why the annotated test class or test method fails as soon as the date is reached:
+
+[source,java,indent=0]
+----
+include::{demo}[tag=fail_at_with_reason]
+----
+
+The `@FailAt` annotation can be used on the class and method level, it will be inherited from higher level containers:
+
+[source,java,indent=0]
+----
+include::{demo}[tag=fail_at_at_class_level]
+----
+
+The `@FailAt` annotation can only be used once per class or method.
+
+== Before and After
+
+The test will be executed normally if the date specified by `date` is the future but a warning entry will be published to the https://junit-pioneer.org/docs/report-entries[test report] to indicate that there might be a problem in the future.
+
+If `date` is today or in the past, the test will fail as the execution condition is not fulfilled anymore.
+
+== Thread-Safety
+
+This extension is safe to use during https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution[parallel test execution].

src/demo/java/org/junitpioneer/jupiter/FailAtExtensionDemo.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junitpioneer.jupiter;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+public class FailAtExtensionDemo {
+
+	// tag::fail_at_simple[]
+	@Test
+	@FailAt(date = "2025-01-01")
+	void test() {
+		// Test will fail as soon as 1st of January 2025 is reached.
+	}
+	// end::fail_at_simple[]
+
+	// tag::fail_at_with_reason[]
+	@Test
+	@DisabledUntil(reason = "We are not allowed to call that method anymore", date = "2025-01-01")
+	void testWithReason() {
+		// Test will fail as soon as 1st of January 2025 is reached.
+	}
+	// end::fail_at_with_reason[]
+
+	@Nested
+	// tag::fail_at_at_class_level[]
+	@FailAt(date = "2025-01-01")
+	class TestClass {
+
+		@Test
+		void test() {
+			// Test will fail as soon as 1st of January 2025 is reached.
+		}
+
+	}
+	// end::fail_at_at_class_level[]
+
+}

src/main/java/org/junitpioneer/jupiter/package-info.java

@@ -10,6 +10,7 @@
  *     <li>{@link org.junitpioneer.jupiter.DisabledUntil}</li>
  *     <li>{@link org.junitpioneer.jupiter.DisableIfTestFails}</li>
  *     <li>{@link org.junitpioneer.jupiter.ExpectedToFail}</li>
+ *     <li>{@link org.junitpioneer.jupiter.FailAt}</li>
  *     <li>{@link org.junitpioneer.jupiter.ReportEntry}</li>
  *     <li>{@link org.junitpioneer.jupiter.RetryingTest}</li>
  *     <li>{@link org.junitpioneer.jupiter.StdIo}</li>