Theories (JUnit API)
Date: 2018-08-04

org.junit.experimental.theories

## Class Theories

- java.lang.Object
- - org.junit.runner.Runner
  - - org.junit.runners.ParentRunner<FrameworkMethod>
    - - org.junit.runners.BlockJUnit4ClassRunner
      - - org.junit.experimental.theories.Theories

- All Implemented Interfaces:
    Describable, Filterable, Sortable

      public class Theories
      extends BlockJUnit4ClassRunner

  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 Also:
    Archived Popper project documentation, Paper on Theories

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Theories.TheoryAnchor`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Theories(java.lang.Class<?> klass)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `collectInitializationErrors(java.util.List<java.lang.Throwable> errors)` Adds to `errors` a throwable for each problem noted with the test class (available from `ParentRunner.getTestClass()`).
    `protected java.util.List<FrameworkMethod>` | `computeTestMethods()` Returns the methods that run tests.
    `Statement` | `methodBlock(FrameworkMethod method)` Returns a Statement that, when executed, either returns normally if `method` passes, or throws an exception if `method` fails.
    `protected void` | `validateConstructor(java.util.List<java.lang.Throwable> errors)` Adds to `errors` if the test class has more than one constructor, or if the constructor takes parameters.
    `protected void` | `validateTestMethods(java.util.List<java.lang.Throwable> errors)` Adds to `errors` for each method annotated with `@Test`that is not a public, void instance method with no arguments.

    - ### Methods inherited from class org.junit.runners.BlockJUnit4ClassRunner

      `createTest, describeChild, getChildren, getTestRules, isIgnored, methodInvoker, possiblyExpectingExceptions, rules, runChild, testName, validateFields, validateInstanceMethods, validateNoNonStaticInnerClass, validateOnlyOneConstructor, validateZeroArgConstructor, withAfters, withBefores, withPotentialTimeout`

    - ### Methods inherited from class org.junit.runners.ParentRunner

      `childrenInvoker, classBlock, classRules, createTestClass, filter, getDescription, getName, getRunnerAnnotations, getTestClass, run, runLeaf, setScheduler, sort, validatePublicVoidNoArgMethods, withAfterClasses, withBeforeClasses`

    - ### Methods inherited from class org.junit.runner.Runner

      `testCount`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Theories

          public Theories(java.lang.Class<?> klass)
                   throws InitializationError

      Throws:
        `InitializationError`

  - ### Method Detail

    - #### collectInitializationErrors

          protected void collectInitializationErrors(java.util.List<java.lang.Throwable> errors)

      Description copied from class: `ParentRunner`
      Adds to `errors` a throwable for each problem noted with the test class (available from `ParentRunner.getTestClass()`). Default implementation adds an error for each method annotated with `@BeforeClass` or `@AfterClass` that is not `public static void` with no arguments.
      Overrides:
        `collectInitializationErrors` in class `BlockJUnit4ClassRunner`

    - #### validateConstructor

          protected void validateConstructor(java.util.List<java.lang.Throwable> errors)

      Description copied from class: `BlockJUnit4ClassRunner`
      Adds to `errors` if the test class has more than one constructor, or if the constructor takes parameters. Override if a subclass requires different validation rules.
      Overrides:
        `validateConstructor` in class `BlockJUnit4ClassRunner`

    - #### validateTestMethods

          protected void validateTestMethods(java.util.List<java.lang.Throwable> errors)

      Description copied from class: `BlockJUnit4ClassRunner`
      Adds to `errors` for each method annotated with `@Test`that is not a public, void instance method with no arguments.
      Overrides:
        `validateTestMethods` in class `BlockJUnit4ClassRunner`

    - #### computeTestMethods

          protected java.util.List<FrameworkMethod> computeTestMethods()

      Description copied from class: `BlockJUnit4ClassRunner`
      Returns the methods that run tests. Default implementation returns all methods annotated with `@Test` on this class and superclasses that are not overridden.
      Overrides:
        `computeTestMethods` in class `BlockJUnit4ClassRunner`

    - #### methodBlock

          public Statement methodBlock(FrameworkMethod method)

      Description copied from class: `BlockJUnit4ClassRunner`
      Returns a Statement that, when executed, either returns normally if `method` passes, or throws an exception if `method` fails. Here is an outline of the default implementation:
      - Invoke `method` on the result of `createTest()`, and throw any exceptions thrown by either operation.
      - HOWEVER, if `method`'s `@Test` annotation has the `expecting` attribute, return normally only if the previous step threw an exception of the correct type, and throw an exception otherwise.
      - HOWEVER, if `method`'s `@Test` annotation has the `timeout` attribute, throw an exception if the previous step takes more than the specified number of milliseconds.
      - ALWAYS run all non-overridden `@Before` methods on this class and superclasses before any of the previous steps; if any throws an Exception, stop execution and pass the exception on.
      - ALWAYS run all non-overridden `@After` methods on this class and superclasses after any of the previous steps; all After methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from After methods into a `MultipleFailureException`.
      - ALWAYS allow `@Rule` fields to modify the execution of the above steps. A `Rule` may prevent all execution of the above steps, or add additional behavior before and after, or modify thrown exceptions. For more information, see `TestRule`
      This can be overridden in subclasses, either by overriding this method, or the implementations creating each sub-statement.
      Overrides:
        `methodBlock` in class `BlockJUnit4ClassRunner`