- title: "Fail Test at a Date"

url: /docs/fail-at/

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 suited for such cases.

The test will fail when the given date is reached.

To mark a test to fail at a given date, add the `@FailAt` annotation like so:

[source,java,indent=0]

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]

The `@FailAt` annotation can be used on the class and method level, it will be inherited from higher-level containers:

[source,java,indent=0]

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 in 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].

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

@FailAt(reason = "We are not allowed anymore", date = "2025-01-01")

void testWithReason() {

// Test will fail with the given reason 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[]

}

package org.junitpioneer.jupiter;

import java.lang.annotation.ElementType;

import java.lang.annotation.Inherited;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

import org.junit.jupiter.api.extension.ExtendWith;

@Retention(RetentionPolicy.RUNTIME)

@Target({ ElementType.METHOD, ElementType.TYPE })

@ExtendWith(FailAtExtension.class)

public @interface FailAt {

/**

String reason() default "";

/**

String date();

}

package org.junitpioneer.jupiter;

import static java.lang.String.format;

import static org.junit.jupiter.api.extension.ConditionEvaluationResult.enabled;

import static org.junitpioneer.internal.PioneerAnnotationUtils.findClosestEnclosingAnnotation;

import java.time.LocalDate;

import java.time.format.DateTimeFormatter;

import java.time.format.DateTimeParseException;

import java.util.Optional;

import org.junit.jupiter.api.extension.ConditionEvaluationResult;

import org.junit.jupiter.api.extension.ExecutionCondition;

import org.junit.jupiter.api.extension.ExtensionConfigurationException;

import org.junit.jupiter.api.extension.ExtensionContext;

import org.opentest4j.AssertionFailedError;

class FailAtExtension implements ExecutionCondition {

private static final DateTimeFormatter ISO_8601 = DateTimeFormatter.ISO_DATE;

@Override

public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) {

return getFailAtDateFromAnnotation(context)

.map(failAtDate -> evaluateFailAtDate(context, failAtDate))

.orElse(enabled("No @FailAt annotation found on element."));

}

private Optional<LocalDate> getFailAtDateFromAnnotation(ExtensionContext context) {

return findClosestEnclosingAnnotation(context, FailAt.class).map(FailAt::date).map(this::parseDate);

}

private LocalDate parseDate(String dateString) {

try {

return LocalDate.parse(dateString, ISO_8601);

}

catch (DateTimeParseException ex) {

throw new ExtensionConfigurationException(

"The `failAtDate` string '" + dateString + "' is not a valid ISO 8601 string.", ex);

}

}

private ConditionEvaluationResult evaluateFailAtDate(ExtensionContext context, LocalDate failAtDate) {

LocalDate today = LocalDate.now();

boolean isBefore = today.isBefore(failAtDate);

String failAtDateString = failAtDate.format(ISO_8601);

String todayDateString = today.format(ISO_8601);

if (isBefore) {

String reportEntry = format(

"The `date` %s is after the current date %s, so `@FailAt` did not fail the test \"%s\". It will do so when the date is reached.",

failAtDateString, todayDateString, context.getUniqueId());

context.publishReportEntry("FailAt", reportEntry);

return enabled(reportEntry);

} else {

String reportEntry = format(

"The current date %s is after or on the `date` %s, so `@FailAt` fails the test \"%s\". Please remove the annotation.",

failAtDateString, todayDateString, context.getUniqueId());

context.publishReportEntry(FailAtExtension.class.getSimpleName(), reportEntry);

String message = format("The current date %s is after or on the `date` %s", todayDateString,

failAtDateString);

throw new AssertionFailedError(message);

}

}

}