JUnit 6.0.1 · org.junit.jupiter.api.extension.TestTemplateInvocationContextProvider

TestTemplateInvocationContextProvider defines the API for Extensions that wish to provide one or multiple contexts for the invocation of a @TestTemplate method.

This extension point makes it possible to execute a test template in different contexts — for example, with different parameters, by preparing the test class instance differently, or multiple times without modifying the context.

This interface defines two main methods: supportsTestTemplate and provideTestTemplateInvocationContexts. The former is called by the framework to determine whether this extension wants to act on a test template that is about to be executed. If so, the latter is called and must return a Stream of TestTemplateInvocationContext instances. Otherwise, this provider is ignored for the execution of the current test template.

A provider that has returned true from its supportsTestTemplate method is called active. When multiple providers are active for a test template method, the Streams returned by their provideTestTemplateInvocationContexts methods will be chained, and the test template method will be invoked using the contexts of all active providers.

An active provider may return zero invocation contexts from its provideTestTemplateInvocationContexts method if it overrides mayReturnZeroTestTemplateInvocationContexts to return true.

Constructor Requirements

Consult the documentation in Extension for details on constructor requirements.

Method Summary

Modifier and Type	Method and Description
public default boolean	Returns: `true` to allow zero contexts, `false` to fail execution in case of zero contexts mayReturnZeroTestTemplateInvocationContexts(ExtensionContext the extension context for the test template method about to be invoked; never `null` context) Signal that this provider may provide zero invocation contexts for the test template method represented by the supplied `context`.
public Stream<? extends TestTemplateInvocationContext>	Returns: a `Stream` of `TestTemplateInvocationContext` instances for the invocation of the test template method; never `null` provideTestTemplateInvocationContexts(ExtensionContext the extension context for the test template method about to be invoked; never `null` context) Provide invocation contexts for the test template method represented by the supplied `context`.
public boolean	Returns: `true` if this provider can provide invocation contexts supportsTestTemplate(ExtensionContext the extension context for the test template method about to be invoked; never `null` context) Determine if this provider supports providing invocation contexts for the test template method represented by the supplied `context`.

Method Detail

mayReturnZeroTestTemplateInvocationContexts back to summary

mayReturnZeroTestTemplateInvocationContexts	back to summary
public default boolean mayReturnZeroTestTemplateInvocationContexts(ExtensionContext context) Signal that this provider may provide zero invocation contexts for the test template method represented by the supplied `context`. If this method returns `false` (which is the default) and the provider returns an empty stream from `provideTestTemplateInvocationContexts`, this will be considered an execution error. Override this method to return `true` to ignore the absence of invocation contexts for this provider. Parameters context:ExtensionContext the extension context for the test template method about to be invoked; never `null` Returns:boolean `true` to allow zero contexts, `false` to fail execution in case of zero contexts Annotations @API status:MAINTAINED since:5.13.3 Since 5.12

public default boolean mayReturnZeroTestTemplateInvocationContexts(ExtensionContext context)

Signal that this provider may provide zero invocation contexts for the test template method represented by the supplied context.

If this method returns false (which is the default) and the provider returns an empty stream from provideTestTemplateInvocationContexts, this will be considered an execution error. Override this method to return true to ignore the absence of invocation contexts for this provider.

Parameters

context:ExtensionContext: the extension context for the test template method about to be invoked; never null

Returns:boolean

true to allow zero contexts, false to fail execution in case of zero contexts

Annotations

@API
status:MAINTAINED
since:5.13.3

Since

5.12

provideTestTemplateInvocationContexts back to summary

provideTestTemplateInvocationContexts	back to summary
public Stream<? extends TestTemplateInvocationContext> provideTestTemplateInvocationContexts(ExtensionContext context) Provide invocation contexts for the test template method represented by the supplied `context`. This method is only called by the framework if `supportsTestTemplate` previously returned `true` for the same `ExtensionContext`; this method is allowed to return an empty `Stream` but not `null`. The returned `Stream` will be properly closed by calling `Stream#close()`, making it safe to use a resource such as `Files.lines()`. Parameters context:ExtensionContext the extension context for the test template method about to be invoked; never `null` Returns:Stream<? extends TestTemplateInvocationContext> a `Stream` of `TestTemplateInvocationContext` instances for the invocation of the test template method; never `null` Exceptions TemplateInvocationValidationException: if a validation fails when while providing or closing the `java.util.stream.Stream`. See Also `supportsTestTemplate`, `ExtensionContext`

public Stream<? extends TestTemplateInvocationContext> provideTestTemplateInvocationContexts(ExtensionContext context)

Provide invocation contexts for the test template method represented by the supplied context.

This method is only called by the framework if supportsTestTemplate previously returned true for the same ExtensionContext; this method is allowed to return an empty Stream but not null.

The returned Stream will be properly closed by calling Stream#close(), making it safe to use a resource such as Files.lines().

Parameters

context:ExtensionContext: the extension context for the test template method about to be invoked; never null

Returns:Stream<? extends TestTemplateInvocationContext>

a Stream of TestTemplateInvocationContext instances for the invocation of the test template method; never null

Exceptions

TemplateInvocationValidationException:: if a validation fails when while providing or closing the java.util.stream.Stream.

supportsTestTemplate back to summary

supportsTestTemplate	back to summary
public boolean supportsTestTemplate(ExtensionContext context) Determine if this provider supports providing invocation contexts for the test template method represented by the supplied `context`. Parameters context:ExtensionContext the extension context for the test template method about to be invoked; never `null` Returns:boolean `true` if this provider can provide invocation contexts See Also `provideTestTemplateInvocationContexts`, `ExtensionContext`

public boolean supportsTestTemplate(ExtensionContext context)

Determine if this provider supports providing invocation contexts for the test template method represented by the supplied context.

Parameters

context:ExtensionContext: the extension context for the test template method about to be invoked; never null

Returns:boolean

true if this provider can provide invocation contexts

public Interface TestTemplateInvocationContextProvider

Constructor Requirements

Method Summary

Method Detail