Module org.junit.platform.engine
Package org.junit.platform.engine.discovery

Class DiscoverySelectors

java.lang.Object
org.junit.platform.engine.discovery.DiscoverySelectors
@API(status=STABLE, since="1.0") public final class DiscoverySelectors extends Object
Collection of static factory methods for creating DiscoverySelectors.
Since:
1.0
See Also:

  • Method Details

    • selectUri

      public static UriSelector selectUri(String uri)
      Create a UriSelector for the supplied URI.
      Parameters:
      uri - the URI to select; never null or blank
      See Also:

    • selectUri

      public static UriSelector selectUri(URI uri)
      Create a UriSelector for the supplied URI.
      Parameters:
      uri - the URI to select; never null
      See Also:

    • selectFile

      public static FileSelector selectFile(String path)
      Create a FileSelector for the supplied file path.

      This method selects the file using the supplied path as is, without verifying if the file exists.

      Parameters:
      path - the path to the file to select; never null or blank
      See Also:

    • selectFile

      public static FileSelector selectFile(File file)
      Create a FileSelector for the supplied file.

      This method selects the file in its canonical form and throws a PreconditionViolationException if the file does not exist.

      Parameters:
      file - the file to select; never null
      See Also:

    • selectFile

      public static FileSelector selectFile(String path, FilePosition position)
      Create a FileSelector for the supplied file path.

      This method selects the file using the supplied path as is, without verifying if the file exists.

      Parameters:
      path - the path to the file to select; never null or blank
      position - the position inside the file; may be null
      See Also:

    • selectFile

      public static FileSelector selectFile(File file, FilePosition position)
      Create a FileSelector for the supplied file.

      This method selects the file in its canonical form and throws a PreconditionViolationException if the file does not exist.

      Parameters:
      file - the file to select; never null
      position - the position inside the file; may be null
      See Also:

    • selectDirectory

      public static DirectorySelector selectDirectory(String path)
      Create a DirectorySelector for the supplied directory path.

      This method selects the directory using the supplied path as is, without verifying if the directory exists.

      Parameters:
      path - the path to the directory to select; never null or blank
      See Also:

    • selectDirectory

      public static DirectorySelector selectDirectory(File directory)
      Create a DirectorySelector for the supplied directory.

      This method selects the directory in its canonical form and throws a PreconditionViolationException if the directory does not exist.

      Parameters:
      directory - the directory to select; never null
      See Also:

    • selectClasspathRoots

      public static List<ClasspathRootSelector> selectClasspathRoots(Set<Path> classpathRoots)
      Create a list of ClasspathRootSelectors for the supplied classpath roots (directories or JAR files).

      Since the supplied paths are converted to URIs, the FileSystem that created them must be the default or one that has been created by an installed FileSystemProvider.

      Since engines are not expected to modify the classpath, the classpath roots represented by the resulting selectors must be on the classpath of the context class loader of the thread that uses these selectors.

      Parameters:
      classpathRoots - set of directories and JAR files in the filesystem that represent classpath roots; never null
      Returns:
      a list of selectors for the supplied classpath roots; elements which do not physically exist in the filesystem will be filtered out
      See Also:

    • selectClasspathResource

      public static ClasspathResourceSelector selectClasspathResource(String classpathResourceName)
      Create a ClasspathResourceSelector for the supplied classpath resource name.

      The name of a classpath resource must follow the semantics for resource paths as defined in ClassLoader.getResource(String).

      If the supplied classpath resource name is prefixed with a slash (/), the slash will be removed.

      Since engines are not expected to modify the classpath, the supplied classpath resource must be on the classpath of the context class loader of the thread that uses the resulting selector.

      Parameters:
      classpathResourceName - the name of the classpath resource; never null or blank
      See Also:

    • selectClasspathResource

      public static ClasspathResourceSelector selectClasspathResource(String classpathResourceName, FilePosition position)
      Create a ClasspathResourceSelector for the supplied classpath resource name.

      The name of a classpath resource must follow the semantics for resource paths as defined in ClassLoader.getResource(String).

      If the supplied classpath resource name is prefixed with a slash (/), the slash will be removed.

      Since engines are not expected to modify the classpath, the supplied classpath resource must be on the classpath of the context class loader of the thread that uses the resulting selector.

      Parameters:
      classpathResourceName - the name of the classpath resource; never null or blank
      position - the position inside the classpath resource; may be null
      See Also:

    • selectClasspathResource

      @API(status=EXPERIMENTAL, since="1.12") public static ClasspathResourceSelector selectClasspathResource(Set<Resource> classpathResources)
      Create a ClasspathResourceSelector for the supplied classpath resources.

      Since engines are not expected to modify the classpath, the supplied resource must be on the classpath of the context class loader of the thread that uses the resulting selector.

      Note: Since Java 9, all resources are on the module path. Either in named or unnamed modules. These resources are also considered to be classpath resources.

      Parameters:
      classpathResources - a set of classpath resources; never null or empty. All resources must have the same name, may not be null or blank.
      Since:
      1.12
      See Also:

    • selectModule

      @API(status=STABLE, since="1.10") public static ModuleSelector selectModule(String moduleName)
      Create a ModuleSelector for the supplied module name.

      The unnamed module is not supported.

      Parameters:
      moduleName - the module name to select; never null or blank
      Since:
      1.1
      See Also:

    • selectModules

      @API(status=STABLE, since="1.10") public static List<ModuleSelector> selectModules(Set<String> moduleNames)
      Create a list of ModuleSelectors for the supplied module names.

      The unnamed module is not supported.

      Parameters:
      moduleNames - the module names to select; never null, never containing null or blank
      Since:
      1.1
      See Also:

    • selectPackage

      public static PackageSelector selectPackage(String packageName)
      Create a PackageSelector for the supplied package name.

      The default package is represented by an empty string ("").

      Parameters:
      packageName - the package name to select; never null and never containing whitespace only
      See Also:

    • selectClass

      public static ClassSelector selectClass(Class<?> clazz)
      Create a ClassSelector for the supplied Class.
      Parameters:
      clazz - the class to select; never null
      See Also:

    • selectClass

      public static ClassSelector selectClass(String className)
      Create a ClassSelector for the supplied class name.
      Parameters:
      className - the fully qualified name of the class to select; never null or blank
      See Also:

    • selectClass

      @API(status=EXPERIMENTAL, since="1.10") public static ClassSelector selectClass(ClassLoader classLoader, String className)
      Create a ClassSelector for the supplied class name and class loader.
      Parameters:
      classLoader - the class loader to use to load the class, or null to signal that the default ClassLoader should be used
      className - the fully qualified name of the class to select; never null or blank
      Since:
      1.10
      See Also:

    • selectMethod

      public static MethodSelector selectMethod(String fullyQualifiedMethodName) throws PreconditionViolationException
      Create a MethodSelector for the supplied fully qualified method name.

      The following formats are supported.

      • [fully qualified class name]#[methodName]
      • [fully qualified class name]#[methodName](parameter type list)

      The parameter type list is a comma-separated list of primitive names or fully qualified class names for the types of parameters accepted by the method.

      Array parameter types may be specified using either the JVM's internal String representation (e.g., [[I for int[][], [Ljava.lang.String; for java.lang.String[], etc.) or source code syntax (e.g., int[][], java.lang.String[], etc.).

      Examples
      MethodFully Qualified Method Name
      java.lang.String.chars()java.lang.String#chars
      java.lang.String.chars()java.lang.String#chars()
      java.lang.String.equalsIgnoreCase(String)java.lang.String#equalsIgnoreCase(java.lang.String)
      java.lang.String.substring(int, int)java.lang.String#substring(int, int)
      example.Calc.avg(int[])example.Calc#avg([I)
      example.Calc.avg(int[])example.Calc#avg(int[])
      example.Matrix.multiply(double[][])example.Matrix#multiply([[D)
      example.Matrix.multiply(double[][])example.Matrix#multiply(double[][])
      example.Service.process(String[])example.Service#process([Ljava.lang.String;)
      example.Service.process(String[])example.Service#process(java.lang.String[])
      example.Service.process(String[][])example.Service#process([[Ljava.lang.String;)
      example.Service.process(String[][])example.Service#process(java.lang.String[][])
      Parameters:
      fullyQualifiedMethodName - the fully qualified name of the method to select; never null or blank
      Throws:
      PreconditionViolationException
      See Also:

    • selectMethod

      @API(status=EXPERIMENTAL, since="1.10") public static MethodSelector selectMethod(ClassLoader classLoader, String fullyQualifiedMethodName) throws PreconditionViolationException
      Create a MethodSelector for the supplied fully qualified method name and class loader.

      See selectMethod(String) for the supported formats for a fully qualified method name.

      Parameters:
      classLoader - the class loader to use to load the method's declaring class, or null to signal that the default ClassLoader should be used
      fullyQualifiedMethodName - the fully qualified name of the method to select; never null or blank
      Throws:
      PreconditionViolationException
      Since:
      1.10
      See Also:

    • selectMethod

      public static MethodSelector selectMethod(String className, String methodName)
      Create a MethodSelector for the supplied class name and method name using the default class loader.
      Parameters:
      className - the fully qualified name of the class in which the method is declared, or a subclass thereof; never null or blank
      methodName - the name of the method to select; never null or blank
      See Also:

    • selectMethod

      @API(status=EXPERIMENTAL, since="1.10") public static MethodSelector selectMethod(ClassLoader classLoader, String className, String methodName)
      Create a MethodSelector for the supplied class name, method name, and class loader.
      Parameters:
      classLoader - the class loader to use to load the class, or null to signal that the default ClassLoader should be used
      className - the fully qualified name of the class in which the method is declared, or a subclass thereof; never null or blank
      methodName - the name of the method to select; never null or blank
      Since:
      1.10
      See Also:

    • selectMethod

      public static MethodSelector selectMethod(String className, String methodName, String parameterTypeNames)
      Create a MethodSelector for the supplied class name, method name, and parameter type names.

      The parameter type names String is typically a comma-separated list of atomic types, fully qualified class names, or array types; however, the exact syntax depends on the underlying test engine.

      Parameters:
      className - the fully qualified name of the class in which the method is declared, or a subclass thereof; never null or blank
      methodName - the name of the method to select; never null or blank
      parameterTypeNames - the parameter type names as a single string; never null though potentially an empty string if the method does not declare parameters
      See Also:

    • selectMethod

      @API(status=EXPERIMENTAL, since="1.10") public static MethodSelector selectMethod(ClassLoader classLoader, String className, String methodName, String parameterTypeNames)
      Create a MethodSelector for the supplied class name, method name, parameter type names, and class loader.

      The parameter type names String is typically a comma-separated list of atomic types, fully qualified class names, or array types; however, the exact syntax depends on the underlying test engine.

      Parameters:
      classLoader - the class loader to use to load the class, or null to signal that the default ClassLoader should be used
      className - the fully qualified name of the class in which the method is declared, or a subclass thereof; never null or blank
      methodName - the name of the method to select; never null or blank
      parameterTypeNames - the parameter type names as a single string; never null though potentially an empty string if the method does not declare any parameters
      Since:
      1.10
      See Also:

    • selectMethod

      public static MethodSelector selectMethod(Class<?> javaClass, String methodName)
      Create a MethodSelector for the supplied Class and method name.
      Parameters:
      javaClass - the class in which the method is declared, or a subclass thereof; never null
      methodName - the name of the method to select; never null or blank
      See Also:

    • selectMethod

      public static MethodSelector selectMethod(Class<?> javaClass, String methodName, String parameterTypeNames)
      Create a MethodSelector for the supplied Class, method name, and parameter type names.

      The parameter type names String is typically a comma-separated list of atomic types, fully qualified class names, or array types; however, the exact syntax depends on the underlying test engine.

      Parameters:
      javaClass - the class in which the method is declared, or a subclass thereof; never null
      methodName - the name of the method to select; never null or blank
      parameterTypeNames - the parameter type names as a single string; never null though potentially an empty string if the method does not declare any parameters
      See Also:

    • selectMethod

      @API(status=EXPERIMENTAL, since="1.10") public static MethodSelector selectMethod(String className, String methodName, Class<?>... parameterTypes)
      Create a MethodSelector for the supplied class name, method name, and parameter types.
      Parameters:
      className - the fully qualified name of the class in which the method is declared, or a subclass thereof; never null or blank
      methodName - the name of the method to select; never null or blank
      parameterTypes - the formal parameter types of the method; never null though potentially empty if the method does not declare parameters
      Since:
      1.10
      See Also:

    • selectMethod

      @API(status=EXPERIMENTAL, since="1.10") public static MethodSelector selectMethod(Class<?> javaClass, String methodName, Class<?>... parameterTypes)
      Create a MethodSelector for the supplied Class, method name, and parameter types.
      Parameters:
      javaClass - the class in which the method is declared, or a subclass thereof; never null
      methodName - the name of the method to select; never null or blank
      parameterTypes - the formal parameter types of the method; never null though potentially empty if the method does not declare parameters
      Since:
      1.10
      See Also:

    • selectMethod

      public static MethodSelector selectMethod(Class<?> javaClass, Method method)
      Create a MethodSelector for the supplied Class and Method.
      Parameters:
      javaClass - the class in which the method is declared, or a subclass thereof; never null
      method - the method to select; never null
      See Also:

    • selectNestedClass

      @API(status=STABLE, since="1.6") public static NestedClassSelector selectNestedClass(List<Class<?>> enclosingClasses, Class<?> nestedClass)
      Create a NestedClassSelector for the supplied nested Class and its enclosing classes.
      Parameters:
      enclosingClasses - the path to the nested class to select; never null or empty
      nestedClass - the nested class to select; never null
      Since:
      1.6
      See Also:

    • selectNestedClass

      @API(status=STABLE, since="1.6") public static NestedClassSelector selectNestedClass(List<String> enclosingClassNames, String nestedClassName)
      Create a NestedClassSelector for the supplied class name and its enclosing classes' names.
      Parameters:
      enclosingClassNames - the names of the enclosing classes; never null or empty
      nestedClassName - the name of the nested class to select; never null or blank
      Since:
      1.6
      See Also:

    • selectNestedClass

      @API(status=EXPERIMENTAL, since="1.10") public static NestedClassSelector selectNestedClass(ClassLoader classLoader, List<String> enclosingClassNames, String nestedClassName)
      Create a NestedClassSelector for the supplied class name, its enclosing classes' names, and class loader.
      Parameters:
      classLoader - the class loader to use to load the enclosing and nested classes, or null to signal that the default ClassLoader should be used
      enclosingClassNames - the names of the enclosing classes; never null or empty
      nestedClassName - the name of the nested class to select; never null or blank
      Since:
      1.10
      See Also:

    • selectNestedMethod

      @API(status=STABLE, since="1.6") public static NestedMethodSelector selectNestedMethod(List<String> enclosingClassNames, String nestedClassName, String methodName)
      Create a NestedMethodSelector for the supplied nested class name and method name.
      Parameters:
      enclosingClassNames - the names of the enclosing classes; never null or empty
      nestedClassName - the name of the nested class to select; never null or blank
      methodName - the name of the method to select; never null or blank
      Since:
      1.6
      See Also:

    • selectNestedMethod

      @API(status=EXPERIMENTAL, since="1.10") public static NestedMethodSelector selectNestedMethod(ClassLoader classLoader, List<String> enclosingClassNames, String nestedClassName, String methodName) throws PreconditionViolationException
      Create a NestedMethodSelector for the supplied nested class name, method name, and class loader.
      Parameters:
      classLoader - the class loader to use to load the method's declaring class, or null to signal that the default ClassLoader should be used
      enclosingClassNames - the names of the enclosing classes; never null or empty
      nestedClassName - the name of the nested class to select; never null or blank
      methodName - the name of the method to select; never null or blank
      Throws:
      PreconditionViolationException
      Since:
      1.10
      See Also:

    • selectNestedMethod

      @API(status=STABLE, since="1.6") public static NestedMethodSelector selectNestedMethod(List<String> enclosingClassNames, String nestedClassName, String methodName, String parameterTypeNames)
      Create a NestedMethodSelector for the supplied nested class name, method name, and parameter type names.

      The parameter type names String is typically a comma-separated list of atomic types, fully qualified class names, or array types; however, the exact syntax depends on the underlying test engine.

      Parameters:
      enclosingClassNames - the names of the enclosing classes; never null or empty
      nestedClassName - the name of the nested class to select; never null or blank
      methodName - the name of the method to select; never null or blank
      parameterTypeNames - the parameter type names as a single string; never null though potentially an empty string if the method does not declare parameters
      Since:
      1.6
      See Also:

    • selectNestedMethod

      @API(status=EXPERIMENTAL, since="1.10") public static NestedMethodSelector selectNestedMethod(ClassLoader classLoader, List<String> enclosingClassNames, String nestedClassName, String methodName, String parameterTypeNames)
      Create a NestedMethodSelector for the supplied nested class name, method name, parameter type names, and class loader.
      Parameters:
      classLoader - the class loader to use to load the method's declaring class, or null to signal that the default ClassLoader should be used
      enclosingClassNames - the names of the enclosing classes; never null or empty
      nestedClassName - the name of the nested class to select; never null or blank
      methodName - the name of the method to select; never null or blank
      parameterTypeNames - the parameter type names as a single string; never null though potentially an empty string if the method does not declare parameters
      Since:
      1.10
      See Also:

    • selectNestedMethod

      @API(status=EXPERIMENTAL, since="1.10") public static NestedMethodSelector selectNestedMethod(List<String> enclosingClassNames, String nestedClassName, String methodName, Class<?>... parameterTypes)
      Create a NestedMethodSelector for the supplied enclosing class names, nested class name, method name, and parameter types.
      Parameters:
      enclosingClassNames - the names of the enclosing classes; never null or empty
      nestedClassName - the name of the nested class to select; never null or blank
      methodName - the name of the method to select; never null or blank
      parameterTypes - the formal parameter types of the method; never null though potentially empty if the method does not declare parameters
      Since:
      1.10
      See Also:

    • selectNestedMethod

      @API(status=STABLE, since="1.6") public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, String methodName)
      Create a NestedMethodSelector for the supplied nested Class and method name.
      Parameters:
      enclosingClasses - the path to the nested class to select; never null or empty
      nestedClass - the nested class to select; never null
      methodName - the name of the method to select; never null or blank
      Since:
      1.6
      See Also:

    • selectNestedMethod

      @API(status=STABLE, since="1.6") public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, String methodName, String parameterTypeNames)
      Create a NestedMethodSelector for the supplied Class, method name, and parameter type names.

      The parameter type names String is typically a comma-separated list of atomic types, fully qualified class names, or array types; however, the exact syntax depends on the underlying test engine.

      Parameters:
      enclosingClasses - the path to the nested class to select; never null or empty
      nestedClass - the nested class to select; never null
      methodName - the name of the method to select; never null or blank
      parameterTypeNames - the parameter type names as a single string; never null though potentially an empty string if the method does not declare parameters
      Since:
      1.6
      See Also:

    • selectNestedMethod

      @API(status=EXPERIMENTAL, since="1.10") public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, String methodName, Class<?>... parameterTypes)
      Create a NestedMethodSelector for the supplied enclosing classes, nested class, method name, and parameter types.
      Parameters:
      enclosingClasses - the path to the nested class to select; never null or empty
      nestedClass - the nested class to select; never null
      methodName - the name of the method to select; never null or blank
      parameterTypes - the formal parameter types of the method; never null though potentially empty if the method does not declare parameters
      Since:
      1.10
      See Also:

    • selectNestedMethod

      @API(status=STABLE, since="1.6") public static NestedMethodSelector selectNestedMethod(List<Class<?>> enclosingClasses, Class<?> nestedClass, Method method)
      Create a NestedMethodSelector for the supplied nested Class and Method.
      Parameters:
      enclosingClasses - the path to the nested class to select; never null or empty
      nestedClass - the nested class to select; never null
      method - the method to select; never null
      Since:
      1.6
      See Also:

    • selectUniqueId

      public static UniqueIdSelector selectUniqueId(UniqueId uniqueId)
      Create a UniqueIdSelector for the supplied UniqueId.
      Parameters:
      uniqueId - the UniqueId to select; never null
      See Also:

    • selectUniqueId

      public static UniqueIdSelector selectUniqueId(String uniqueId)
      Create a UniqueIdSelector for the supplied unique ID.
      Parameters:
      uniqueId - the unique ID to select; never null or blank
      See Also:

    • selectIteration

      @API(status=EXPERIMENTAL, since="1.9") public static IterationSelector selectIteration(DiscoverySelector parentSelector, int... iterationIndices)
      Create an IterationSelector for the supplied parent selector and iteration indices.
      Parameters:
      parentSelector - the parent selector to select iterations for; never null
      iterationIndices - the iteration indices to select; never null or empty
      Since:
      1.9
      See Also:

    • parse

      @API(status=EXPERIMENTAL, since="1.11") public static Optional<? extends DiscoverySelector> parse(String identifier)
      Parse the supplied string representation of a DiscoverySelectorIdentifier.
      Parameters:
      identifier - the string representation of a DiscoverySelectorIdentifier; never null or blank
      Returns:
      an Optional containing the corresponding DiscoverySelector; never null but potentially empty
      Since:
      1.11
      See Also:

    • parse

      @API(status=EXPERIMENTAL, since="1.11") public static Optional<? extends DiscoverySelector> parse(DiscoverySelectorIdentifier identifier)
      Parse the supplied DiscoverySelectorIdentifier.
      Parameters:
      identifier - the DiscoverySelectorIdentifier to parse; never null
      Returns:
      an Optional containing the corresponding DiscoverySelector; never null but potentially empty
      Since:
      1.11
      See Also:

    • parseAll

      @API(status=EXPERIMENTAL, since="1.11") public static Stream<? extends DiscoverySelector> parseAll(String... identifiers)
      Parse the supplied string representations of DiscoverySelectorIdentifiers.
      Parameters:
      identifiers - the string representations of DiscoverySelectorIdentifiers to parse; never null
      Returns:
      a stream of the corresponding DiscoverySelectors; never null but potentially empty
      Since:
      1.11
      See Also:

    • parseAll

      @API(status=EXPERIMENTAL, since="1.11") public static Stream<? extends DiscoverySelector> parseAll(Collection<DiscoverySelectorIdentifier> identifiers)
      Parse the supplied DiscoverySelectorIdentifiers.
      Parameters:
      identifiers - the DiscoverySelectorIdentifiers to parse; never null
      Returns:
      a stream of the corresponding DiscoverySelectors; never null but potentially empty
      Since:
      1.11
      See Also: