org.junit.jupiter.api.Timeout Maven / Gradle / Ivy
/*
* Copyright 2015-2020 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
*
* https://www.eclipse.org/legal/epl-v20.html
*/
package org.junit.jupiter.api;
import static org.apiguardian.api.API.Status.STABLE;
import java.lang.annotation.Documented;
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 java.util.concurrent.TimeUnit;
import org.apiguardian.api.API;
/**
* {@code @Timeout} is used to define a timeout for a method or all testable
* methods within one class and its {@link Nested @Nested} classes.
*
* This annotation may also be used on lifecycle methods annotated with
* {@link BeforeAll @BeforeAll}, {@link BeforeEach @BeforeEach},
* {@link AfterEach @AfterEach}, or {@link AfterAll @AfterAll}.
*
*
Applying this annotation to a test class has the same effect as applying
* it to all testable methods, i.e. all methods annotated or meta-annotated with
* {@link Test @Test}, {@link TestFactory @TestFactory}, or
* {@link TestTemplate @TestTemplate}, but not to its lifecycle methods.
*
*
Default Timeouts
*
* If this annotation is not present, no timeout will be used unless a
* default timeout is defined via one of the following configuration parameters:
*
*
* - {@code junit.jupiter.execution.timeout.default}
* - Default timeout for all testable and lifecycle methods
* - {@code junit.jupiter.execution.timeout.testable.method.default}
* - Default timeout for all testable methods
* - {@code junit.jupiter.execution.timeout.test.method.default}
* - Default timeout for {@link Test @Test} methods
* - {@code junit.jupiter.execution.timeout.testtemplate.method.default}
* - Default timeout for {@link TestTemplate @TestTemplate} methods
* - {@code junit.jupiter.execution.timeout.testfactory.method.default}
* - Default timeout for {@link TestFactory @TestFactory} methods
* - {@code junit.jupiter.execution.timeout.lifecycle.method.default}
* - Default timeout for all lifecycle methods
* - {@code junit.jupiter.execution.timeout.beforeall.method.default}
* - Default timeout for {@link BeforeAll @BeforeAll} methods
* - {@code junit.jupiter.execution.timeout.beforeeach.method.default}
* - Default timeout for {@link BeforeEach @BeforeEach} methods
* - {@code junit.jupiter.execution.timeout.aftereach.method.default}
* - Default timeout for {@link AfterEach @AfterEach} methods
* - {@code junit.jupiter.execution.timeout.afterall.method.default}
* - Default timeout for {@link AfterAll @AfterAll} methods
*
*
* More specific configuration parameters override less specific ones. For
* example, {@code junit.jupiter.execution.timeout.test.method.default}
* overrides {@code junit.jupiter.execution.timeout.testable.method.default}
* which overrides {@code junit.jupiter.execution.timeout.default}.
*
*
Values must be in the following, case-insensitive format:
* {@code [ns|μs|ms|s|m|h|d]}. The space between the number and the
* unit may be omitted. Specifying no unit is equivalent to using seconds.
*
*
* Value Equivalent annotation {@code 42} {@code @Timeout(42)} {@code 42 ns} {@code @Timeout(value = 42, unit = NANOSECONDS)} {@code 42 μs} {@code @Timeout(value = 42, unit = MICROSECONDS)} {@code 42 ms} {@code @Timeout(value = 42, unit = MILLISECONDS)} {@code 42 s} {@code @Timeout(value = 42, unit = SECONDS)} {@code 42 m} {@code @Timeout(value = 42, unit = MINUTES)} {@code 42 h} {@code @Timeout(value = 42, unit = HOURS)} {@code 42 d} {@code @Timeout(value = 42, unit = DAYS)}
*
* @since 5.5
*/
@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@API(status = STABLE, since = "5.7")
public @interface Timeout {
/**
* The duration of this timeout.
*
* @return timeout duration; must be a positive number
*/
long value();
/**
* The time unit of this timeout.
*
* @return time unit
* @see TimeUnit
*/
TimeUnit unit() default TimeUnit.SECONDS;
}