From e304688f14e9f73d7984bdb148f45f6f7ecc337b Mon Sep 17 00:00:00 2001 From: Alex Yursha Date: Fri, 30 May 2014 13:23:57 +0300 Subject: [PATCH] Add javadoc to some classes in org.junit.experimental.theories --- .../theories/ParameterSupplier.java | 36 +++++++++++++ .../junit/experimental/theories/Theories.java | 50 +++++++++++++++++++ .../junit/experimental/theories/Theory.java | 5 ++ .../theories/suppliers/TestedOnSupplier.java | 4 ++ 4 files changed, 95 insertions(+) diff --git a/src/main/java/org/junit/experimental/theories/ParameterSupplier.java b/src/main/java/org/junit/experimental/theories/ParameterSupplier.java index 11916b31699e..bac8b34282e2 100644 --- a/src/main/java/org/junit/experimental/theories/ParameterSupplier.java +++ b/src/main/java/org/junit/experimental/theories/ParameterSupplier.java @@ -2,6 +2,42 @@ import java.util.List; +/** + * Abstract parent class for suppliers of input data points for theories. Extend this class to customize how {@link + * org.junit.experimental.theories.Theories Theories} runner + * finds accepted data points. Then use your class together with @ParametersSuppliedBy on input + * parameters for theories. + * + *

+ * For example, here is a supplier for values between two integers, and an annotation that references it: + * + * 

+ *     @Retention(RetentionPolicy.RUNTIME)
+ *     @ParametersSuppliedBy(BetweenSupplier.class)
+ *     public @interface Between {
+ *         int first();
+ *
+ *         int last();
+ *     }
+ *
+ *     public static class BetweenSupplier extends ParameterSupplier {
+ *         @Override
+ *         public List<PotentialAssignment> getValueSources(ParameterSignature sig) {
+ *             List<PotentialAssignment> list = new ArrayList<PotentialAssignment>();
+ *             Between annotation = (Between) sig.getSupplierAnnotation();
+ *
+ *             for (int i = annotation.first(); i <= annotation.last(); i++)
+ *                 list.add(PotentialAssignment.forValue("ints", i));
+ *             return list;
+ *         }
+ *     }
+ *
+ *

+ * + * @see org.junit.experimental.theories.ParametersSuppliedBy + * @see org.junit.experimental.theories.Theories + * @see org.junit.experimental.theories.FromDataPoints + */ public abstract class ParameterSupplier { public abstract List getValueSources(ParameterSignature sig) throws Throwable; } diff --git a/src/main/java/org/junit/experimental/theories/Theories.java b/src/main/java/org/junit/experimental/theories/Theories.java index 7fe02327f534..76c5104db058 100644 --- a/src/main/java/org/junit/experimental/theories/Theories.java +++ b/src/main/java/org/junit/experimental/theories/Theories.java @@ -18,6 +18,56 @@ import org.junit.runners.model.Statement; import org.junit.runners.model.TestClass; +/** + * The Theories runner allows to test a certain functionality against a subset of an infinite set of data points. + *

+ * A Theory is a piece of functionality (a method) that is executed against several data inputs called data points. + * To make a test method a theory you mark it with @Theory. To create a data point you create a public + * field in your test class and mark it with @DataPoint. The Theories runner then executes your test + * method as many times as the number of data points declared, providing a different data point as + * the input argument on each invocation. + *

+ *

+ * A Theory differs from standard test method in that it captures some aspect of the intended behavior in possibly + * infinite numbers of scenarios which corresponds to the number of data points declared. Using assumptions and + * assertions properly together with covering multiple scenarios with different data points can make your tests more + * flexible and bring them closer to scientific theories (hence the name). + *

+ *

+ * For example: + * 

+ *
+ * @RunWith(Theories.class)
+ * public class UserTest {
+ *      @DataPoint
+ *      public static String GOOD_USERNAME = "optimus";
+ *      @DataPoint
+ *      public static String USERNAME_WITH_SLASH = "optimus/prime";
+ *
+ *      @Theory
+ *      public void filenameIncludesUsername(String username) {
+ *          assumeThat(username, not(containsString("/")));
+ *          assertThat(new User(username).configFileName(), containsString(username));
+ *      }
+ * }
+ *
+ * This makes it clear that the user's filename should be included in the config file name, + * only if it doesn't contain a slash. Another test or theory might define what happens when a username does contain + * a slash. UserTest will attempt to run filenameIncludesUsername on every compatible data + * point defined in the class. If any of the assumptions fail, the data point is silently ignored. If all of the + * assumptions pass, but an assertion fails, the test fails. + *

+ * Defining general statements as theories allows data point reuse across a bunch of functionality tests and also + * allows automated tools to search for new, unexpected data points that expose bugs. + *

+ *

+ * The support for Theories has been absorbed from the Popper project, and more complete documentation can be found + * from that projects archived documentation. + *

+ * + * @see Archived Popper project documentation + * @see Paper on Theories + */ public class Theories extends BlockJUnit4ClassRunner { public Theories(Class klass) throws InitializationError { super(klass); diff --git a/src/main/java/org/junit/experimental/theories/Theory.java b/src/main/java/org/junit/experimental/theories/Theory.java index e5542b5f31ca..0b9f2c4121fe 100644 --- a/src/main/java/org/junit/experimental/theories/Theory.java +++ b/src/main/java/org/junit/experimental/theories/Theory.java @@ -6,6 +6,11 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Marks test methods that should be read as theories by the {@link org.junit.experimental.theories.Theories Theories} runner. + * + * @see org.junit.experimental.theories.Theories + */ @Retention(RetentionPolicy.RUNTIME) @Target(METHOD) public @interface Theory { diff --git a/src/main/java/org/junit/experimental/theories/suppliers/TestedOnSupplier.java b/src/main/java/org/junit/experimental/theories/suppliers/TestedOnSupplier.java index d540f76645a4..dc3d0c9ce326 100644 --- a/src/main/java/org/junit/experimental/theories/suppliers/TestedOnSupplier.java +++ b/src/main/java/org/junit/experimental/theories/suppliers/TestedOnSupplier.java @@ -7,6 +7,10 @@ import org.junit.experimental.theories.ParameterSupplier; import org.junit.experimental.theories.PotentialAssignment; +/** + * @see org.junit.experimental.theories.suppliers.TestedOn + * @see org.junit.experimental.theories.ParameterSupplier + */ public class TestedOnSupplier extends ParameterSupplier { @Override public List getValueSources(ParameterSignature sig) {