1b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabotpackage org.junit.rules; 2b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot 3b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabotimport org.junit.runner.Description; 4b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabotimport org.junit.runners.model.Statement; 5b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot 6b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot/** 7b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * A TestRule is an alteration in how a test method, or set of test methods, 8b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * is run and reported. A {@link TestRule} may add additional checks that cause 9b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * a test that would otherwise fail to pass, or it may perform necessary setup or 10b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * cleanup for tests, or it may observe test execution to report it elsewhere. 11b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * {@link TestRule}s can do everything that could be done previously with 12b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * methods annotated with {@link org.junit.Before}, 13b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * {@link org.junit.After}, {@link org.junit.BeforeClass}, or 14b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * {@link org.junit.AfterClass}, but they are more powerful, and more easily 15b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * shared 16b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * between projects and classes. 17b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * 18b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * The default JUnit test runners for suites and 19b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * individual test cases recognize {@link TestRule}s introduced in two different 20b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * ways. {@link org.junit.Rule} annotates method-level 21b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * {@link TestRule}s, and {@link org.junit.ClassRule} 22b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * annotates class-level {@link TestRule}s. See Javadoc for those annotations 23b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * for more information. 24b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * 25b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * Multiple {@link TestRule}s can be applied to a test or suite execution. The 26b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * {@link Statement} that executes the method or suite is passed to each annotated 27b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * {@link org.junit.Rule} in turn, and each may return a substitute or modified 28b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * {@link Statement}, which is passed to the next {@link org.junit.Rule}, if any. For 29b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * examples of how this can be useful, see these provided TestRules, 30b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * or write your own: 31b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * 32b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <ul> 33b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link ErrorCollector}: collect multiple errors in one test method</li> 34b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link ExpectedException}: make flexible assertions about thrown exceptions</li> 35b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link ExternalResource}: start and stop a server, for example</li> 36b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link TemporaryFolder}: create fresh files, and delete after test</li> 37b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link TestName}: remember the test name for use during the method</li> 38b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link TestWatcher}: add logic at events during method execution</li> 39b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link Timeout}: cause test to fail after a set time</li> 40b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * <li>{@link Verifier}: fail test if object state ends up incorrect</li> 41b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * </ul> 42b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot */ 43b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabotpublic interface TestRule { 44b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot /** 45b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * Modifies the method-running {@link Statement} to implement this 46b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * test-running rule. 47b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * 48b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * @param base The {@link Statement} to be modified 49b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * @param description A {@link Description} of the test implemented in {@code base} 50b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * @return a new statement, which may be the same as {@code base}, 51b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot * a wrapper around {@code base}, or a completely new Statement. 52b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot */ 53b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot Statement apply(Statement base, Description description); 54b3823db9f1192d8c81345740b3e65bd6738ba55bBrett Chabot} 55