org.junit.experimental.theories
Class Theories

java.lang.Object
  extended by org.junit.runner.Runner
      extended by org.junit.runners.ParentRunner<FrameworkMethod>
          extended by org.junit.runners.BlockJUnit4ClassRunner
              extended by org.junit.experimental.theories.Theories
All Implemented Interfaces:
Describable, Filterable, Orderable, 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 username 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. If no parameters can be found that satisfy all assumptions, 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
static class Theories.TheoryAnchor
           
 
Constructor Summary
  Theories(Class<?> klass)
           
protected Theories(TestClass testClass)
           
 
Method Summary
protected  void collectInitializationErrors(List<Throwable> errors)
          Adds to errors a throwable for each problem noted with the test class (available from ParentRunner.getTestClass()).
protected  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(List<Throwable> errors)
          Adds to errors if the test class has more than one constructor, or if the constructor takes parameters.
protected  void validateTestMethods(List<Throwable> errors)
          Adds to errors for each method annotated with @Testthat is not a public, void instance method with no arguments.
 
Methods inherited from class org.junit.runners.BlockJUnit4ClassRunner
createTest, 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, order, run, runLeaf, setScheduler, sort, validatePublicVoidNoArgMethods, withAfterClasses, withBeforeClasses, withInterruptIsolation
 
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(Class<?> klass)
         throws InitializationError
Throws:
InitializationError

Theories

protected Theories(TestClass testClass)
            throws InitializationError
Throws:
InitializationError
Since:
4.13
Method Detail

collectInitializationErrors

protected void collectInitializationErrors(List<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(List<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(List<Throwable> errors)
Description copied from class: BlockJUnit4ClassRunner
Adds to errors for each method annotated with @Testthat is not a public, void instance method with no arguments.

Overrides:
validateTestMethods in class BlockJUnit4ClassRunner

computeTestMethods

protected 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: This can be overridden in subclasses, either by overriding this method, or the implementations creating each sub-statement.

Overrides:
methodBlock in class BlockJUnit4ClassRunner


Copyright © 2002–2021 JUnit. All rights reserved.