Add support for multiple class name patterns to JUnitPlatform runner

Issue: #474

documentation/src/docs/asciidoc/release-notes-5.0.0-M3.adoc

@@ -47,6 +47,7 @@ on GitHub.
   classpath scanning.
 * `ClassNameFilter.includeClassNamePattern` is now deprecated in favor of
   `ClassNameFilter.includeClassNamePatterns`.
+* `@IncludeClassNamePattern` is now deprecated in favor of `@IncludeClassNamePatterns`.
 * The `-p` command-line option for configuring additional classpath entries for the
   `ConsoleLauncher` has been renamed to `-cp` in order to align with the option names for
   the standard `java` executable. In addition, a new `--class-path` alias has been
@@ -88,6 +89,8 @@ on GitHub.
   that it can be executed as a test on the JUnit Platform).
 * Multiple regular expressions that are combined using OR semantics can now be passed to
   `ClassNameFilter.includeClassNamePatterns`.
+* Multiple regular expressions that are combined using OR semantics can now be passed via
+  `@IncludeClassNamePatterns` to the `JUnitPlatform` runner.
 
 
 [[release-notes-5.0.0-m3-junit-jupiter]]

documentation/src/test/java/example/DocumentationTestSuite.java

@@ -11,7 +11,7 @@
 package example;
 
 import org.junit.platform.runner.ExcludeTags;
-import org.junit.platform.runner.IncludeClassNamePattern;
+import org.junit.platform.runner.IncludeClassNamePatterns;
 import org.junit.platform.runner.JUnitPlatform;
 import org.junit.platform.runner.SelectPackages;
 import org.junit.runner.RunWith;
@@ -31,7 +31,7 @@
  */
 @RunWith(JUnitPlatform.class)
 @SelectPackages("example")
-@IncludeClassNamePattern(".+(Tests|Demo)$")
+@IncludeClassNamePatterns(".+(Tests|Demo)$")
 @ExcludeTags("exclude")
 public class DocumentationTestSuite {
 }

junit-jupiter-engine/src/test/java/org/junit/jupiter/JupiterTestSuite.java

@@ -10,7 +10,7 @@
 
 package org.junit.jupiter;
 
-import org.junit.platform.runner.IncludeClassNamePattern;
+import org.junit.platform.runner.IncludeClassNamePatterns;
 import org.junit.platform.runner.IncludeEngines;
 import org.junit.platform.runner.JUnitPlatform;
 import org.junit.platform.runner.SelectPackages;
@@ -34,7 +34,7 @@
  */
 @RunWith(JUnitPlatform.class)
 @SelectPackages("org.junit.jupiter")
-@IncludeClassNamePattern(".*Tests?")
+@IncludeClassNamePatterns(".*Tests?")
 @IncludeEngines("junit-jupiter")
 public class JupiterTestSuite {
 }

junit-platform-runner/src/main/java/org/junit/platform/runner/IncludeClassNamePattern.java

@@ -10,7 +10,7 @@
 
 package org.junit.platform.runner;
 
-import static org.junit.platform.commons.meta.API.Usage.Maintained;
+import static org.junit.platform.commons.meta.API.Usage.Deprecated;
 
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
@@ -33,12 +33,14 @@
  * @since 1.0
  * @see JUnitPlatform
  * @see org.junit.platform.engine.discovery.ClassNameFilter#includeClassNamePatterns
+ * @deprecated Please use {@link IncludeClassNamePatterns}.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Inherited
 @Documented
-@API(Maintained)
+@API(Deprecated)
+@Deprecated
 public @interface IncludeClassNamePattern {
 
 	/**

junit-platform-runner/src/main/java/org/junit/platform/runner/IncludeClassNamePatterns.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2015-2016 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution and is available at
+ *
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+
+package org.junit.platform.runner;
+
+import static org.junit.platform.commons.meta.API.Usage.Maintained;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.platform.commons.meta.API;
+import org.junit.platform.engine.discovery.ClassNameFilter;
+
+/**
+ * {@code @IncludeClassNamePatterns} specifies regular expressions that are used
+ * to match against fully qualified class names when running a test suite via
+ * {@code @RunWith(JUnitPlatform.class)}.
+ *
+ * <p>The patterns are combined using OR semantics, i.e. if the fully
+ * qualified name of a class matches against at least one of the patterns,
+ * the class will be included in the test plan.
+ *
+ * @since 1.0
+ * @see JUnitPlatform
+ * @see ClassNameFilter#includeClassNamePatterns
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@Inherited
+@Documented
+@API(Maintained)
+public @interface IncludeClassNamePatterns {
+
+	/**
+	 * Regular expression used to match against fully qualified class names.
+	 *
+	 * <p>Defaults to {@code "^.*Tests?$"} which matches against class names
+	 * ending in {@code Test} or {@code Tests} (in any package).
+	 */
+	String[] value() default { ClassNameFilter.STANDARD_INCLUDE_PATTERN };
+
+}

junit-platform-runner/src/main/java/org/junit/platform/runner/JUnitPlatform.java

@@ -63,14 +63,14 @@
  * in order to be picked up by IDEs and build tools.
  *
  * <p>When used on a class that serves as a test suite and the
- * {@link IncludeClassNamePattern} annotation is not present, the default
+ * {@link IncludeClassNamePatterns} annotation is not present, the default
  * include pattern {@value org.junit.platform.engine.discovery.ClassNameFilter#STANDARD_INCLUDE_PATTERN}
  * is used to avoid loading classes unnecessarily.
  *
  * @since 1.0
  * @see SelectPackages
  * @see SelectClasses
- * @see IncludeClassNamePattern
+ * @see IncludeClassNamePatterns
  * @see IncludeTags
  * @see ExcludeTags
  * @see IncludeEngines
@@ -158,9 +158,9 @@ private <T> List<DiscoverySelector> transform(T[] sourceElements, Function<T, Di
 	}
 
 	private void addIncludeClassNamePatternFilter(LauncherDiscoveryRequestBuilder requestBuilder, boolean isSuite) {
-		String pattern = getIncludeClassNamePattern(isSuite);
-		if (!pattern.isEmpty()) {
-			requestBuilder.filters(includeClassNamePatterns(pattern));
+		String[] patterns = getIncludeClassNamePatterns(isSuite);
+		if (patterns.length > 0) {
+			requestBuilder.filters(includeClassNamePatterns(patterns));
 		}
 	}
 
@@ -216,9 +216,35 @@ private String[] getExcludedEngineIds() {
 		return getValueFromAnnotation(ExcludeEngines.class, ExcludeEngines::value, EMPTY_STRING_ARRAY);
 	}
 
-	private String getIncludeClassNamePattern(boolean isSuite) {
-		return getValueFromAnnotation(IncludeClassNamePattern.class, IncludeClassNamePattern::value,
-			isSuite ? STANDARD_INCLUDE_PATTERN : EMPTY_STRING).trim();
+	@SuppressWarnings("deprecation")
+	private String[] getIncludeClassNamePatterns(boolean isSuite) {
+		String[] patterns = getIncludeClassNamePatterns();
+		if (patterns.length == 0 && isSuite) {
+			return new String[] { STANDARD_INCLUDE_PATTERN };
+		}
+		Preconditions.containsNoNullElements(patterns, "IncludeClassNamePatterns must not contain null elements");
+		trim(patterns);
+		return patterns;
+	}
+
+	private void trim(String[] patterns) {
+		for (int i = 0; i < patterns.length; i++) {
+			patterns[i] = patterns[i].trim();
+		}
+	}
+
+	@SuppressWarnings("deprecation")
+	private String[] getIncludeClassNamePatterns() {
+		String[] patterns = getValueFromAnnotation(IncludeClassNamePatterns.class, IncludeClassNamePatterns::value,
+			new String[0]);
+		String patternFromDeprecatedAnnotation = getValueFromAnnotation(IncludeClassNamePattern.class,
+			IncludeClassNamePattern::value, EMPTY_STRING);
+		Preconditions.condition(patterns.length == 0 || patternFromDeprecatedAnnotation.isEmpty(),
+			"You must not specify both @IncludeClassNamePattern and @IncludeClassNamePatterns");
+		if (patterns.length == 0 && !patternFromDeprecatedAnnotation.isEmpty()) {
+			patterns = new String[] { patternFromDeprecatedAnnotation };
+		}
+		return patterns;
 	}
 
 	private <A extends Annotation, V> V getValueFromAnnotation(Class<A> annotationClass, Function<A, V> extractor,

junit-platform-surefire-provider/src/test/java/org/junit/platform/surefire/provider/SurefireProviderTestSuite.java

@@ -10,7 +10,7 @@
 
 package org.junit.platform.surefire.provider;
 
-import org.junit.platform.runner.IncludeClassNamePattern;
+import org.junit.platform.runner.IncludeClassNamePatterns;
 import org.junit.platform.runner.IncludeEngines;
 import org.junit.platform.runner.JUnitPlatform;
 import org.junit.platform.runner.SelectPackages;
@@ -33,7 +33,7 @@
  */
 @RunWith(JUnitPlatform.class)
 @SelectPackages("org.junit.platform.surefire.provider")
-@IncludeClassNamePattern(".*Tests?")
+@IncludeClassNamePatterns(".*Tests?")
 @IncludeEngines("junit-jupiter")
 public class SurefireProviderTestSuite {
 }

junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineTestSuite.java

@@ -10,7 +10,7 @@
 
 package org.junit.vintage.engine;
 
-import org.junit.platform.runner.IncludeClassNamePattern;
+import org.junit.platform.runner.IncludeClassNamePatterns;
 import org.junit.platform.runner.IncludeEngines;
 import org.junit.platform.runner.JUnitPlatform;
 import org.junit.platform.runner.SelectPackages;
@@ -33,7 +33,7 @@
  */
 @RunWith(JUnitPlatform.class)
 @SelectPackages("org.junit.vintage.engine")
-@IncludeClassNamePattern(".*Tests?")
+@IncludeClassNamePatterns(".*Tests?")
 @IncludeEngines("junit-jupiter")
 public class VintageTestEngineTestSuite {
 }

platform-tests/src/test/java/org/junit/platform/JUnitPlatformTestSuite.java

@@ -10,7 +10,7 @@
 
 package org.junit.platform;
 
-import org.junit.platform.runner.IncludeClassNamePattern;
+import org.junit.platform.runner.IncludeClassNamePatterns;
 import org.junit.platform.runner.IncludeEngines;
 import org.junit.platform.runner.JUnitPlatform;
 import org.junit.platform.runner.SelectPackages;
@@ -33,7 +33,7 @@
  */
 @RunWith(JUnitPlatform.class)
 @SelectPackages("org.junit.platform")
-@IncludeClassNamePattern(".*Tests?")
+@IncludeClassNamePatterns(".*Tests?")
 @IncludeEngines("junit-jupiter")
 public class JUnitPlatformTestSuite {
 }

platform-tests/src/test/java/org/junit/platform/runner/JUnitPlatformRunnerTests.java

@@ -42,6 +42,7 @@
 
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.platform.commons.util.PreconditionViolationException;
 import org.junit.platform.engine.EngineDiscoveryRequest;
 import org.junit.platform.engine.EngineExecutionListener;
 import org.junit.platform.engine.ExecutionRequest;
@@ -225,8 +226,10 @@ class TestCase {
 		}
 
 		@Test
-		void addsExplicitClassNameFilterToRequestWhenFilterClassNameAnnotationIsPresent() throws Exception {
+		void addsExplicitClassNameFilterToRequestWhenDeprecatedIncludeClassNamePatternAnnotationIsPresent()
+				throws Exception {
 
+			@SuppressWarnings("deprecation")
 			@IncludeClassNamePattern(".*Foo")
 			class TestCase {
 			}
@@ -237,6 +240,76 @@ class TestCase {
 			assertThat(getOnlyElement(filters).toString()).contains(".*Foo");
 		}
 
+		@Test
+		void addsExplicitClassNameFilterToRequestWhenIncludeClassNamePatternsAnnotationIsPresent() throws Exception {
+
+			@IncludeClassNamePatterns({ ".*Foo", "Bar.*" })
+			class TestCase {
+			}
+
+			LauncherDiscoveryRequest request = instantiateRunnerAndCaptureGeneratedRequest(TestCase.class);
+
+			List<ClassNameFilter> filters = request.getDiscoveryFiltersByType(ClassNameFilter.class);
+			assertThat(getOnlyElement(filters).toString()).contains(".*Foo", "Bar.*");
+		}
+
+		@Test
+		void usesStandardIncludePatternWhenIncludeClassNamePatternsAnnotationIsPresentWithoutArguments()
+				throws Exception {
+
+			@IncludeClassNamePatterns
+			class TestCase {
+			}
+
+			LauncherDiscoveryRequest request = instantiateRunnerAndCaptureGeneratedRequest(TestCase.class);
+
+			List<ClassNameFilter> filters = request.getDiscoveryFiltersByType(ClassNameFilter.class);
+			assertThat(getOnlyElement(filters).toString()).contains(STANDARD_INCLUDE_PATTERN);
+		}
+
+		@Test
+		void addsExplicitClassNameFilterWhenIncludeClassNamePatternsAnnotationIsPresentWithEmptyArguments()
+				throws Exception {
+
+			@IncludeClassNamePatterns({})
+			class TestCase {
+			}
+
+			LauncherDiscoveryRequest request = instantiateRunnerAndCaptureGeneratedRequest(TestCase.class);
+
+			List<ClassNameFilter> filters = request.getDiscoveryFiltersByType(ClassNameFilter.class);
+			assertThat(filters).isEmpty();
+		}
+
+		@Test
+		void throwsExceptionWhenBothIncludeClassNamePatternsAnnotationsArePresent() throws Exception {
+
+			@SuppressWarnings("deprecation")
+			@IncludeClassNamePattern("foo")
+			@IncludeClassNamePatterns("foo")
+			class TestCase {
+			}
+
+			PreconditionViolationException exception = assertThrows(PreconditionViolationException.class,
+				() -> instantiateRunnerAndCaptureGeneratedRequest(TestCase.class));
+
+			assertThat(exception).hasMessage(
+				"You must not specify both @IncludeClassNamePattern and @IncludeClassNamePatterns");
+		}
+
+		@Test
+		void trimsArgumentsOfIncludeClassNamePatternsAnnotation() throws Exception {
+
+			@IncludeClassNamePatterns({ " foo", "bar " })
+			class TestCase {
+			}
+
+			LauncherDiscoveryRequest request = instantiateRunnerAndCaptureGeneratedRequest(TestCase.class);
+
+			List<ClassNameFilter> filters = request.getDiscoveryFiltersByType(ClassNameFilter.class);
+			assertThat(getOnlyElement(filters).toString()).contains("'foo'", "'bar'");
+		}
+
 		@Test
 		void convertsTestIdentifiersIntoDescriptions() throws Exception {