Class SuiteLauncherDiscoveryRequestBuilder

java.lang.Object

org.junit.platform.suite.commons.SuiteLauncherDiscoveryRequestBuilder

@API(status=INTERNAL,
     since="1.8",
     consumers={"org.junit.platform.suite.engine","org.junit.platform.runner"})
public final class SuiteLauncherDiscoveryRequestBuilder
extends Object

The SuiteLauncherDiscoveryRequestBuilder provides a light-weight DSL for generating a LauncherDiscoveryRequest specifically tailored for suite execution.

Example

SuiteLauncherDiscoveryRequestBuilder.request()
  .selectors(
       selectPackage("org.example.user"),
       selectClass("org.example.payment.PaymentTests"),
       selectClass(ShippingTests.class),
       selectMethod("org.example.order.OrderTests#test1"),
       selectMethod("org.example.order.OrderTests#test2()"),
       selectMethod("org.example.order.OrderTests#test3(java.lang.String)"),
       selectMethod("org.example.order.OrderTests", "test4"),
       selectMethod(OrderTests.class, "test5"),
       selectMethod(OrderTests.class, testMethod),
       selectClasspathRoots(Collections.singleton(Paths.get("/my/local/path1"))),
       selectUniqueId("unique-id-1"),
       selectUniqueId("unique-id-2")
  )
  .filters(
       includeEngines("junit-jupiter", "spek"),
       // excludeEngines("junit-vintage"),
       includeTags("fast"),
       // excludeTags("slow"),
       includeClassNamePatterns(".*Test[s]?")
       // includeClassNamePatterns("org\.example\.tests.*")
  )
  .configurationParameter("key", "value")
  .enableImplicitConfigurationParameters(true)
  .applyConfigurationParametersFromSuite(MySuite.class)
  .applySelectorsAndFiltersFromSuite(MySuite.class)
  .build();

Since:

1.8

See Also:

• DiscoverySelectors
• ClassNameFilter
• EngineFilter
• TagFilter

Field Summary

Fields

Modifier and Type	Field	Description
private final LauncherDiscoveryRequestBuilder	delegate
private boolean	enableParentConfigurationParameters
private boolean	filterStandardClassNamePatterns
private boolean	includeClassNamePatternsUsed
private ConfigurationParameters	parentConfigurationParameters
private final Set<String>	selectedClassNames

Constructor Summary

Constructors

Modifier	Constructor	Description
private	SuiteLauncherDiscoveryRequestBuilder()

Method Summary

Modifier and Type	Method	Description
private void	addClassAndMethodSelectors(Class<?> suiteClass)
private void	addExcludeFilters(Class<?> suiteClass)
private void	addIncludeFilters(Class<?> suiteClass)
private void	addOtherSelectors(Class<?> suiteClass)
SuiteLauncherDiscoveryRequestBuilder	applyConfigurationParametersFromSuite(Class<?> suiteClass)	Apply a suite's annotation-based configuration to this builder.
SuiteLauncherDiscoveryRequestBuilder	applySelectorsAndFiltersFromSuite(Class<?> suiteClass)	Apply a suite's annotation-based discovery selectors and filters to this builder.
LauncherDiscoveryRequest	build()	Build the LauncherDiscoveryRequest that has been configured via this builder.
SuiteLauncherDiscoveryRequestBuilder	configurationParameter(String key, String value)	Add the supplied configuration parameter to the request.
SuiteLauncherDiscoveryRequestBuilder	configurationParameters(Map<String,String> configurationParameters)	Add all supplied configuration parameters to the request.
SuiteLauncherDiscoveryRequestBuilder	configurationParametersResource(String resourceFile)
private ClassNameFilter	createIncludeClassNameFilter(String... patterns)
SuiteLauncherDiscoveryRequestBuilder	enableImplicitConfigurationParameters(boolean enabled)	Configure whether implicit configuration parameters should be considered.
SuiteLauncherDiscoveryRequestBuilder	filters(Filter<?>... filters)	Add all supplied filters to the request.
SuiteLauncherDiscoveryRequestBuilder	filterStandardClassNamePatterns(boolean filterStandardClassNamePatterns)	Specify whether to filter standard class name patterns.
private static <A extends Annotation, V> Optional<V[]>	findAnnotationValues(AnnotatedElement element, Class<A> annotationType, Function<A,V[]> valueExtractor)
SuiteLauncherDiscoveryRequestBuilder	listener(LauncherDiscoveryListener listener)
SuiteLauncherDiscoveryRequestBuilder	outputDirectoryCreator(OutputDirectoryCreator outputDirectoryCreator)
SuiteLauncherDiscoveryRequestBuilder	parentConfigurationParameters(ConfigurationParameters parentConfigurationParameters)	Set the parent configuration parameters to use for the request.
private static String	prefixErrorMessageForInvalidSelectMethodUsage(Class<?> suiteClass, String detailMessage)
static SuiteLauncherDiscoveryRequestBuilder	request()	Create a new SuiteLauncherDiscoveryRequestBuilder.
private List<ClassSelector>	selectClasses(Class<?> suiteClass, SelectClasses annotation)
private MethodSelector	selectMethod(Class<?> suiteClass, SelectMethod annotation)
SuiteLauncherDiscoveryRequestBuilder	selectors(List<? extends DiscoverySelector> selectors)	Add all supplied selectors to the request.
SuiteLauncherDiscoveryRequestBuilder	selectors(DiscoverySelector... selectors)	Add all supplied selectors to the request.
SuiteLauncherDiscoveryRequestBuilder	suite(Class<?> suiteClass)	Deprecated. as of JUnit Platform 1.11 in favor of applyConfigurationParametersFromSuite(Class) and applySelectorsAndFiltersFromSuite(Class)
private static Stream<ClassSelector>	toClassSelectors(Class<?> suiteClass, SelectClasses annotation)
private static MethodSelector	toMethodSelector(Class<?> suiteClass, Class<?> type, String typeName, Class<?>[] parameterTypes, String methodName, String parameterTypeNames)
private MethodSelector	toMethodSelector(Class<?> suiteClass, SelectMethod annotation)
private static MethodSelector	toMethodSelectorFromFQMN(Class<?> suiteClass, SelectMethod annotation)
private static Optional<String[]>	trimmed(String[] patterns)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

delegate

private final LauncherDiscoveryRequestBuilder delegate

selectedClassNames

private final Set<String> selectedClassNames

includeClassNamePatternsUsed

private boolean includeClassNamePatternsUsed

filterStandardClassNamePatterns

private boolean filterStandardClassNamePatterns

parentConfigurationParameters

private ConfigurationParameters parentConfigurationParameters

enableParentConfigurationParameters

private boolean enableParentConfigurationParameters

Constructor Details

SuiteLauncherDiscoveryRequestBuilder

private SuiteLauncherDiscoveryRequestBuilder()

Method Details

request

public static SuiteLauncherDiscoveryRequestBuilder request()

Create a new SuiteLauncherDiscoveryRequestBuilder.

Returns:

a new builder

selectors

public SuiteLauncherDiscoveryRequestBuilder selectors(DiscoverySelector... selectors)

Add all supplied selectors to the request.

Parameters:

selectors - the DiscoverySelectors to add; never null

Returns:

this builder for method chaining

selectors

public SuiteLauncherDiscoveryRequestBuilder selectors(List<? extends DiscoverySelector> selectors)

Add all supplied selectors to the request.

Parameters:

selectors - the DiscoverySelectors to add; never null

Returns:

this builder for method chaining

filters

public SuiteLauncherDiscoveryRequestBuilder filters(Filter<?>... filters)

Add all supplied filters to the request.

The filters are combined using AND semantics, i.e. all of them have to include a resource for it to end up in the test plan.

Warning: be cautious when registering multiple competing include EngineFilters or multiple competing exclude EngineFilters for the same discovery request since doing so will likely lead to undesirable results (i.e., zero engines being active).

Parameters:

filters - the Filters to add; never null

Returns:

this builder for method chaining

filterStandardClassNamePatterns

public SuiteLauncherDiscoveryRequestBuilder filterStandardClassNamePatterns(boolean filterStandardClassNamePatterns)

Specify whether to filter standard class name patterns.

If set to true, standard class name patterns are filtered.

Parameters:

filterStandardClassNamePatterns - true to filter standard class name patterns, false otherwise

Returns:

this builder for method chaining

configurationParameter

public SuiteLauncherDiscoveryRequestBuilder configurationParameter(String key,
 String value)

Add the supplied configuration parameter to the request.

Parameters:

key - the configuration parameter key under which to store the value; never null or blank

value - the value to store

Returns:

this builder for method chaining

configurationParameters

public SuiteLauncherDiscoveryRequestBuilder configurationParameters(Map<String,String> configurationParameters)

Add all supplied configuration parameters to the request.

Parameters:

configurationParameters - the map of configuration parameters to add; never null

Returns:

this builder for method chaining

See Also:

• configurationParameter(String, String)

configurationParametersResource

public SuiteLauncherDiscoveryRequestBuilder configurationParametersResource(String resourceFile)

parentConfigurationParameters

public SuiteLauncherDiscoveryRequestBuilder parentConfigurationParameters(ConfigurationParameters parentConfigurationParameters)

Set the parent configuration parameters to use for the request.

Any explicit configuration parameters configured via configurationParameter(String, String) or configurationParameters(Map) takes precedence over the supplied configuration parameters.

Parameters:

parentConfigurationParameters - the parent instance to use for looking up configuration parameters that have not been explicitly configured; never null

Returns:

this builder for method chaining

See Also:

• configurationParameter(String, String)
• configurationParameters(Map)

enableImplicitConfigurationParameters

public SuiteLauncherDiscoveryRequestBuilder enableImplicitConfigurationParameters(boolean enabled)

Configure whether implicit configuration parameters should be considered.

By default, in addition to those parameters that are passed explicitly to this builder, configuration parameters are read from system properties and from the junit-platform.properties classpath resource. Passing false to this method, disables the latter two sources so that only explicit configuration parameters are taken into account.

Parameters:

enabled - true if implicit configuration parameters should be considered

Returns:

this builder for method chaining

See Also:

• configurationParameter(String, String)
• configurationParameters(Map)

outputDirectoryCreator

public SuiteLauncherDiscoveryRequestBuilder outputDirectoryCreator(OutputDirectoryCreator outputDirectoryCreator)

listener

@API(status=INTERNAL,
     since="1.13")
public SuiteLauncherDiscoveryRequestBuilder listener(LauncherDiscoveryListener listener)

suite

@Deprecated
@API(status=DEPRECATED,
     since="1.11")
public SuiteLauncherDiscoveryRequestBuilder suite(Class<?> suiteClass)

Deprecated.

as of JUnit Platform 1.11 in favor of applyConfigurationParametersFromSuite(Class) and applySelectorsAndFiltersFromSuite(Class)

Apply a suite's annotation-based configuration, selectors, and filters to this builder.

Parameters:

suiteClass - the class to apply the annotations from; never null

Returns:

this builder for method chaining

See Also:

• Suite

applyConfigurationParametersFromSuite

public SuiteLauncherDiscoveryRequestBuilder applyConfigurationParametersFromSuite(Class<?> suiteClass)

Apply a suite's annotation-based configuration to this builder.

This will apply the configuration from the following annotations.

• ConfigurationParameter
• DisableParentConfigurationParameters

Parameters:

suiteClass - the class to apply the configuration annotations from; never null

Returns:

this builder for method chaining

Since:

1.11

See Also:

• Suite

applySelectorsAndFiltersFromSuite

public SuiteLauncherDiscoveryRequestBuilder applySelectorsAndFiltersFromSuite(Class<?> suiteClass)

Apply a suite's annotation-based discovery selectors and filters to this builder.

This will apply the configuration from the following annotations.

• ExcludeClassNamePatterns
• ExcludeEngines
• ExcludePackages
• ExcludeTags
• IncludeClassNamePatterns
• IncludeEngines
• IncludePackages
• IncludeTags
• SelectClasses
• SelectClasspathResource
• SelectDirectories
• SelectFile
• SelectMethod
• SelectModules
• SelectUris
• SelectPackages
• Select

Parameters:

suiteClass - the class to apply the discovery selectors and filter annotations from; never null

Returns:

this builder for method chaining

Since:

1.11

See Also:

• Suite

addExcludeFilters

private void addExcludeFilters(Class<?> suiteClass)

addClassAndMethodSelectors

private void addClassAndMethodSelectors(Class<?> suiteClass)

addIncludeFilters

private void addIncludeFilters(Class<?> suiteClass)

addOtherSelectors

private void addOtherSelectors(Class<?> suiteClass)

build

public LauncherDiscoveryRequest build()

Build the LauncherDiscoveryRequest that has been configured via this builder.

selectClasses

private List<ClassSelector> selectClasses(Class<?> suiteClass,
 SelectClasses annotation)

toClassSelectors

private static Stream<ClassSelector> toClassSelectors(Class<?> suiteClass,
 SelectClasses annotation)

selectMethod

private MethodSelector selectMethod(Class<?> suiteClass,
 SelectMethod annotation)

toMethodSelector

private MethodSelector toMethodSelector(Class<?> suiteClass,
 SelectMethod annotation)

toMethodSelectorFromFQMN

private static MethodSelector toMethodSelectorFromFQMN(Class<?> suiteClass,
 SelectMethod annotation)

toMethodSelector

private static MethodSelector toMethodSelector(Class<?> suiteClass,
 Class<?> type,
 String typeName,
 Class<?>[] parameterTypes,
 String methodName,
 String parameterTypeNames)

prefixErrorMessageForInvalidSelectMethodUsage

private static String prefixErrorMessageForInvalidSelectMethodUsage(Class<?> suiteClass,
 String detailMessage)

createIncludeClassNameFilter

private ClassNameFilter createIncludeClassNameFilter(String... patterns)

findAnnotationValues

private static <A extends Annotation, V>
Optional<V[]> findAnnotationValues(AnnotatedElement element,
 Class<A> annotationType,
 Function<A,V[]> valueExtractor)

trimmed

private static Optional<String[]> trimmed(String[] patterns)