com.googlecode.kevinarpe.papaya.testing
Interface TestClassFinder

public interface TestClassFinder

Finds Class references by recursively scanning a directory for source files. This class can be used to build dynamic test suites. To construct a new instance, see TestClassFinderUtils.newInstance().

An interface is used instead of a concrete class to make mocking and testing easier.

Example:

List<Class<?>> classList =
     TestClassFinderUtils.newInstance()
         .withRootDir(new File("src/test"))
         .withIncludePatterns(Pattern.compile("Test\\.java"))
         .findAsList();
 

Author:

Kevin Connor ARPE (kevinarpe@gmail.com)

Method Summary

Class<?>[]	findAsArray() This is a convenience method to call findAsList().
List<Class<?>>	findAsList() Searches recursively from the root directory to find Java sources files and returns the corresponding Class for each matching file.
List<Pattern>	withExcludePatterns() Retrieves the list of patterns used to include source files.
TestClassFinder	withExcludePatterns(List<Pattern> filePathPatternList) Constructs a new instance with a new list of patterns used to exclude source files.
TestClassFinder	withExcludePatterns(Pattern filePathPattern, Pattern... moreFilePathPatternsArr) This is a convenience method to call withExcludePatterns(List).
List<Pattern>	withIncludePatterns() Retrieves the list of patterns used to include source files.
TestClassFinder	withIncludePatterns(List<Pattern> filePathPatternList) Constructs a new instance with a new list of patterns used to include source files.
TestClassFinder	withIncludePatterns(Pattern filePathPattern, Pattern... moreFilePathPatternsArr) This is a convenience method to call withIncludePatterns(List).
File	withRootDirPath() Retrieves root directory to use when finding test classes.
TestClassFinder	withRootDirPath(File rootDirPath) Constructs a new instance with new root directory to use when finding test classes.

Method Detail

withRootDirPath

TestClassFinder withRootDirPath(File rootDirPath)

Constructs a new instance with new root directory to use when finding test classes. For projects that use Maven, path new File("./src/test") is a good choice.

Parameters:

rootDirPath - Path to root directory to search for test classes. Must not be null.

Returns:

new instance with new root directory

Throws:

NullPointerException - if rootDirPath is null

See Also:

TestClassFinderUtils.DEFAULT_ROOT_DIR_PATH, withRootDirPath()

withRootDirPath

File withRootDirPath()

Retrieves root directory to use when finding test classes. Default is the user working directory from system property "user.dir".

Returns:

root directory

See Also:

TestClassFinderUtils.DEFAULT_ROOT_DIR_PATH, withRootDirPath(File)

withIncludePatterns

TestClassFinder withIncludePatterns(Pattern filePathPattern,
                                    Pattern... moreFilePathPatternsArr)

This is a convenience method to call withIncludePatterns(List).

Throws:

NullPointerException - if filePathPattern or moreFilePathPatternsArr (or any element) is null

withIncludePatterns

TestClassFinder withIncludePatterns(List<Pattern> filePathPatternList)

Constructs a new instance with a new list of patterns used to include source files. To exclude files by pattern, see withExcludePatterns(List).

Matching is performed with Matcher.find(), which does not require the entire input string to match, like Matcher.matches(). If anchoring is required, the patterns must explicitly include "^" (start anchor) or "$" (end anchor).

Parameters:

filePathPatternList -

• List of patterns to match absolute file paths
• Example: "ExternalTest\\.java$"
• To match all files use: "."
• Must not be null, but may be empty

Returns:

new instance with new list of include patterns

Throws:

NullPointerException - if filePathPatternList (or any element) is null

IllegalArgumentException - if filePathPatternList is empty

See Also:

TestClassFinderUtils.DEFAULT_INCLUDE_PATTERN_LIST, withIncludePatterns(Pattern, Pattern...), withIncludePatterns(), withExcludePatterns(List)

withIncludePatterns

List<Pattern> withIncludePatterns()

Retrieves the list of patterns used to include source files. Default is a single pattern to match all files: "."

Returns:

list of include patterns. Never null or empty.

See Also:

TestClassFinderUtils.DEFAULT_INCLUDE_PATTERN_LIST, withIncludePatterns(List), withExcludePatterns()

withExcludePatterns

TestClassFinder withExcludePatterns(Pattern filePathPattern,
                                    Pattern... moreFilePathPatternsArr)

This is a convenience method to call withExcludePatterns(List).

Throws:

NullPointerException - if filePathPattern or moreFilePathPatternsArr (or any element) is null

withExcludePatterns

TestClassFinder withExcludePatterns(List<Pattern> filePathPatternList)

Constructs a new instance with a new list of patterns used to exclude source files. To include files by pattern, see withIncludePatterns(List).

Matching is performed with Matcher.find(), which does not require the entire input string to match, like Matcher.matches(). If anchoring is required, the patterns must explicitly include "^" (start anchor) or "$" (end anchor).

Parameters:

filePathPatternList -

• List of patterns to match absolute file paths
• Example: "ExternalTest\\.java$"
• Must not be null, but may be empty

Returns:

new instance with new list of exclude patterns

Throws:

NullPointerException - if filePathPatternList (or any element) is null

See Also:

TestClassFinderUtils.DEFAULT_EXCLUDE_PATTERN_LIST, withIncludePatterns(Pattern, Pattern...), withIncludePatterns(), withIncludePatterns(List)

withExcludePatterns

List<Pattern> withExcludePatterns()

Retrieves the list of patterns used to include source files. Default is empty list (no patterns to exclude source files).

Returns:

list of include patterns. Never null or empty.

See Also:

TestClassFinderUtils.DEFAULT_EXCLUDE_PATTERN_LIST, withExcludePatterns(List), withIncludePatterns()

findAsList

List<Class<?>> findAsList()

Searches recursively from the root directory to find Java sources files and returns the corresponding Class for each matching file. Three class types are automatically excluded: nested, inner, and abstract classes.

If a source file matches at least one include pattern and matches zero exclude patterns, it will be included in the result.

If SLF4J logging is enabled:

• One line is logged at debug level for the root directory
• One line is logged at debug level for each normal (regular) file

Returns:

list of top-level classes. May be empty, but never null.

Throws:

ClassNotFoundRuntimeException - if a Class cannot be found for a source file

See Also:

findAsArray()

findAsArray

Class<?>[] findAsArray()

This is a convenience method to call findAsList().