Package org.junit.jupiter.api.extension

Interface ClassTemplateInvocationContextProvider

All Superinterfaces:

Extension

@API(status=MAINTAINED,
     since="5.13.3")
public interface ClassTemplateInvocationContextProvider
extends Extension

ClassTemplateInvocationContextProvider defines the API for Extensions that wish to provide one or multiple contexts for the invocation of a @ClassTemplate.

This extension point makes it possible to execute a class 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: supportsClassTemplate(org.junit.jupiter.api.extension.ExtensionContext) and provideClassTemplateInvocationContexts(org.junit.jupiter.api.extension.ExtensionContext). The former is called by the framework to determine whether this extension wants to act on a container template that is about to be executed. If so, the latter is called and must return a Stream of ClassTemplateInvocationContext instances. Otherwise, this provider is ignored for the execution of the current class template.

A provider that has returned true from its supportsClassTemplate(org.junit.jupiter.api.extension.ExtensionContext) method is called active. When multiple providers are active for a class template, the Streams returned by their provideClassTemplateInvocationContexts(org.junit.jupiter.api.extension.ExtensionContext) methods will be chained, and the class template method will be invoked using the contexts of all active providers.

An active provider may return zero invocation contexts from its provideClassTemplateInvocationContexts(org.junit.jupiter.api.extension.ExtensionContext) method if it overrides mayReturnZeroClassTemplateInvocationContexts(org.junit.jupiter.api.extension.ExtensionContext) to return true.

Constructor Requirements

Consult the documentation in Extension for details on constructor requirements.

Since:

5.13

See Also:

ClassTemplate, ClassTemplateInvocationContext

Method Summary

Modifier and Type	Method	Description
default boolean	mayReturnZeroClassTemplateInvocationContexts(ExtensionContext context)	Signal that this provider may provide zero invocation contexts for the class template represented by the supplied context.
java.util.stream.Stream<? extends ClassTemplateInvocationContext>	provideClassTemplateInvocationContexts(ExtensionContext context)	Provide invocation contexts for the class template represented by the supplied context.
boolean	supportsClassTemplate(ExtensionContext context)	Determine if this provider supports providing invocation contexts for the class template represented by the supplied context.

Method Detail

supportsClassTemplate

boolean supportsClassTemplate(ExtensionContext context)

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

Parameters:

context - the extension context for the class template about to be invoked; never null

Returns:

true if this provider can provide invocation contexts

See Also:

provideClassTemplateInvocationContexts(org.junit.jupiter.api.extension.ExtensionContext), ExtensionContext

provideClassTemplateInvocationContexts

java.util.stream.Stream<? extends ClassTemplateInvocationContext> provideClassTemplateInvocationContexts(ExtensionContext context)

Provide invocation contexts for the class template represented by the supplied context.

This method is only called by the framework if supportsClassTemplate(org.junit.jupiter.api.extension.ExtensionContext) 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 BaseStream.close(), making it safe to use a resource such as Files.lines().

Parameters:

context - the extension context for the class template about to be invoked; never null

Returns:

a Stream of ClassTemplateInvocationContext instances for the invocation of the class template; never null

Throws:

TemplateInvocationValidationException - if a validation fails when while providing or closing the Stream.

See Also:

supportsClassTemplate(org.junit.jupiter.api.extension.ExtensionContext), ExtensionContext

mayReturnZeroClassTemplateInvocationContexts

default boolean mayReturnZeroClassTemplateInvocationContexts(ExtensionContext context)

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

If this method returns false (which is the default) and the provider returns an empty stream from provideClassTemplateInvocationContexts(org.junit.jupiter.api.extension.ExtensionContext), 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 - the extension context for the class template about to be invoked; never null

Returns:

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