Merge pull request #22 from pholser/master

Bringing 4.12 changes into theories subtree.

Author: David Saff

theories/.gitignore

@@ -1,4 +1,5 @@
 target
+.idea/
 *.iml
 *.ipr
 *.iws

theories/README.md

@@ -3,9 +3,9 @@ JUnit Theories Runner
 
 This is a port of the JUnit theories runner into junit.contrib.
 
-In addition to being current with the theories implementation in the latest release of JUnit and
+In addition to being current with the theories implementation in JUnit 4.12 and
 depending on its core, this implementation contains a resolution for
-[JUnit GitHub issue 64](http://github.com/KentBeck/junit/issues/64), making it possible for
+[JUnit GitHub issue 64](http://github.com/junit-team/junit/issues/64), making it possible for
 [junit-quickcheck](http://github.com/pholser/junit-quickcheck) to generate values for theory
 parameters involving generics in a safe manner.
 
@@ -14,8 +14,24 @@ so that the one in the core can be removed, meaning that this runner can evolve
 releases of JUnit.
 
 **PLEASE NOTE**: The classes that comprise this rendition of the JUnit theories runner are packaged
-as `org.junit.contrib.theories.*`, rather than `org.junit.experimental.theories.*`. Be careful not
-to intermix the two.
+as `org.junit.contrib.theories.*`, rather than `org.junit.experimental.theories.*`. Be mindful of
+which one you're using.
+
+## Downloading
+
+Releases are synced to the central Maven repository. Declare a dependency element in your POM like so:
+
+    ...
+    <dependencies>
+      ...
+      <dependency>
+        <groupId>org.junit.contrib</groupId>
+        <artifactId>junit-theories</artifactId>
+        <version>4.12</version>
+      </dependency>
+      ...
+    </dependencies>
+    ...
 
 ### What is a theory?
 
@@ -84,9 +100,9 @@ We can eliminate duplicated test logic sometimes by using parameterized tests:
 Neither of these tests expresses important characteristics we want the the answers given by
 `PrimeFactors.of()` to exhibit: No matter what positive integer you give the method...
 
-* The factors should be prime
-* The factors should multiply together to give the original integer
-* No two factorizations of two distinct integers are identical
+* The factors must be prime
+* The factors must multiply together to give the original integer
+* Factorizations of two distinct integers must themselves be distinct (the Fundamental Theorem of Arithmetic)
 
 Whenever we want to express characteristics of a test subject that hold for entire classes of
 inputs, and we can express the characteristics in terms of inputs and outputs, we can codify these

theories/pom.xml

@@ -1,17 +1,15 @@
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
         <groupId>org.sonatype.oss</groupId>
         <artifactId>oss-parent</artifactId>
-        <version>7</version>
+        <version>9</version>
     </parent>
 
     <groupId>org.junit.contrib</groupId>
     <artifactId>junit-theories</artifactId>
-    <version>4.11-SNAPSHOT</version>
+    <version>4.13-SNAPSHOT</version>
     <packaging>jar</packaging>
     <name>junit-theories</name>
     <description>JUnit theories runner</description>
@@ -28,8 +26,8 @@
         </license>
     </licenses>
     <scm>
-        <connection>scm:git:ssh://[email protected]:pholser/junit-theories.git</connection>
-        <developerConnection>scm:git:ssh://[email protected]:pholser/junit-theories.git</developerConnection>
+        <connection>scm:git:[email protected]:pholser/junit-theories.git</connection>
+        <developerConnection>scm:git:[email protected]:pholser/junit-theories.git</developerConnection>
         <url>http://github.com/pholser/junit-theories</url>
     </scm>
     <developers>
@@ -49,7 +47,7 @@
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
-            <version>4.11</version>
+            <version>4.12</version>
         </dependency>
         <dependency>
             <groupId>org.javaruntype</groupId>

theories/src/main/java/org/junit/contrib/theories/DataPoint.java

@@ -1,11 +1,49 @@
 package org.junit.contrib.theories;
 
-import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-@Target({ElementType.METHOD, ElementType.FIELD})
-@Retention(RetentionPolicy.RUNTIME)
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * <p>Marking a field or method with this annotation will cause the field value or the value returned by the method
+ * to be used as a potential value for a theory parameter in that class, when run with the {@link Theories} runner.</p>
+ *
+ * <p>A data point is only considered as a potential value for parameters for which its type is assignable.
+ * When multiple data points exist with overlapping types, more control can be obtained by naming each data point
+ * using the value of this annotation, e.g. with <code>&#064;DataPoint({"dataset1", "dataset2"})</code>, and then
+ * specifying which named set to consider as potential values for each parameter using the
+ * {@link FromDataPoints} annotation.</p>
+ *
+ * <p>Parameters with no specified source will use all data points that are assignable to the parameter type
+ * as potential values, including named sets of data points.</p>
+ *
+ * <pre>
+ * &#064;DataPoint
+ * public static String dataPoint = "value";
+ *
+ * &#064;DataPoint("generated")
+ * public static String generatedDataPoint() {
+ *     return "generated value";
+ * }
+ *
+ * &#064;Theory
+ * public void theoryMethod(String param) {
+ *     ...
+ * }
+ * </pre>
+ *
+ * @see DataPoint
+ * @see FromDataPoints
+ * @see Theories
+ * @see Theory
+ */
+@Retention(RUNTIME)
+@Target({FIELD, METHOD})
 public @interface DataPoint {
+    String[] value() default {};
+
+    Class<? extends Throwable>[] ignoredExceptions() default {};
 }

theories/src/main/java/org/junit/contrib/theories/DataPoints.java

@@ -1,8 +1,54 @@
 package org.junit.contrib.theories;
 
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
-@Retention(RetentionPolicy.RUNTIME)
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * <p>Marking an array or iterable-typed field or method with this annotation will cause the values in the array
+ * or iterable given to be used as potential value for theory parameters in that class when run with the
+ * {@link Theories} runner.</p>
+ *
+ * <p>Data Points will only be considered as potential values for parameters for which their types are assignable.
+ * When multiple sets of DataPoints exist with overlapping types, more control can be obtained by naming the
+ * data points using the value of this annotation, e.g. with <code>&#064;DataPoints({"dataset1", "dataset2"})</code>,
+ * and then specifying which named set to consider as potential values for each parameter using the
+ * {@link FromDataPoints} annotation.</p>
+ *
+ * <p>Parameters with no specified source will use all data points that are assignable to the parameter type as
+ * potential values, including named sets of data points.</p>
+ *
+ * <p>Data points methods whose array types aren't assignable from the target parameter type (and so can't possibly
+ * return relevant values) will not be called when generating values for that parameter. Iterable-typed data points
+ * methods must always be called though, as this information is not available here after generic type erasure,
+ * so expensive methods returning iterable data points are a bad idea.</p>
+ *
+ * <pre>
+ * &#064;DataPoints
+ * public static String[] dataPoints = new String[] { ... };
+ *
+ * &#064;DataPoints
+ * public static String[] generatedDataPoints() {
+ *     return new String[] { ... };
+ * }
+ *
+ * &#064;Theory
+ * public void theoryMethod(String param) {
+ *     ...
+ * }
+ * </pre>
+ *
+ * @see DataPoint
+ * @see FromDataPoints
+ * @see Theories
+ * @see Theory
+ */
+@Retention(RUNTIME)
+@Target({ FIELD, METHOD })
 public @interface DataPoints {
+    String[] value() default {};
+
+    Class<? extends Throwable>[] ignoredExceptions() default {};
 }

theories/src/main/java/org/junit/contrib/theories/FromDataPoints.java

@@ -0,0 +1,53 @@
+package org.junit.contrib.theories;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import org.junit.contrib.theories.internal.SpecificDataPointsSupplier;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+/**
+ * <p>Marking a parameter of a {@link Theory} method with this annotation will limit the data points considered
+ * as potential values for that parameter to only the {@link DataPoints} with the given name.</p>
+ *
+ * <p>Data points without names will not be considered as values for any parameters annotated with
+ * &#064FromDataPoints.</p>
+ *
+ * <pre>
+ * &#064;DataPoints
+ * public static String[] unnamed = new String[] { ... };
+ *
+ * &#064;DataPoints("regexes")
+ * public static String[] regexStrings = new String[] { ... };
+ *
+ * &#064;DataPoints({"forMatching", "alphanumeric"})
+ * public static String[] testStrings = new String[] { ... };
+ *
+ * &#064;Theory
+ * public void stringTheory(String param) {
+ *     // This will be called with every value in 'regexStrings',
+ *     // 'testStrings' and 'unnamed'.
+ * }
+ *
+ * &#064;Theory
+ * public void regexTheory(&#064;FromDataPoints("regexes") String regex,
+ *                         &#064;FromDataPoints("forMatching") String value) {
+ *     // This will be called with only the values in 'regexStrings' as
+ *     // regex, only the values in 'testStrings' as value, and none
+ *     // of the values in 'unnamed'.
+ * }
+ * </pre>
+ *
+ * @see DataPoint
+ * @see DataPoints
+ * @see Theories
+ * @see Theory
+ */
+@Retention(RUNTIME)
+@Target(PARAMETER)
+@ParametersSuppliedBy(SpecificDataPointsSupplier.class)
+public @interface FromDataPoints {
+    String value();
+}