001/* 002 * Copyright 2002-2019 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.test.context; 018 019/** 020 * {@code TestExecutionListener} defines a <em>listener</em> API for reacting to 021 * test execution events published by the {@link TestContextManager} with which 022 * the listener is registered. 023 * 024 * <p>Note that not all testing frameworks support all lifecycle callbacks defined 025 * in this API. For example, {@link #beforeTestExecution} and 026 * {@link #afterTestExecution} are not supported in conjunction with JUnit 4 when 027 * using the {@link org.springframework.test.context.junit4.rules.SpringMethodRule 028 * SpringMethodRule}. 029 * 030 * <p>This interface provides empty {@code default} implementations for all methods. 031 * Concrete implementations can therefore choose to override only those methods 032 * suitable for the task at hand. 033 * 034 * <p>Concrete implementations must provide a {@code public} no-args constructor, 035 * so that listeners can be instantiated transparently by tools and configuration 036 * mechanisms. 037 * 038 * <p>Implementations may optionally declare the position in which they should 039 * be ordered among the chain of default listeners via the 040 * {@link org.springframework.core.Ordered Ordered} interface or 041 * {@link org.springframework.core.annotation.Order @Order} annotation. See 042 * {@link TestContextBootstrapper#getTestExecutionListeners()} for details. 043 * 044 * <p>Spring provides the following out-of-the-box implementations (all of 045 * which implement {@code Ordered}): 046 * <ul> 047 * <li>{@link org.springframework.test.context.web.ServletTestExecutionListener 048 * ServletTestExecutionListener}</li> 049 * <li>{@link org.springframework.test.context.support.DirtiesContextBeforeModesTestExecutionListener 050 * DirtiesContextBeforeModesTestExecutionListener}</li> 051 * <li>{@link org.springframework.test.context.support.DependencyInjectionTestExecutionListener 052 * DependencyInjectionTestExecutionListener}</li> 053 * <li>{@link org.springframework.test.context.support.DirtiesContextTestExecutionListener 054 * DirtiesContextTestExecutionListener}</li> 055 * <li>{@link org.springframework.test.context.transaction.TransactionalTestExecutionListener 056 * TransactionalTestExecutionListener}</li> 057 * <li>{@link org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener 058 * SqlScriptsTestExecutionListener}</li> 059 * <li>{@link org.springframework.test.context.event.EventPublishingTestExecutionListener 060 * EventPublishingTestExecutionListener}</li> 061 * </ul> 062 * 063 * @author Sam Brannen 064 * @author Juergen Hoeller 065 * @since 2.5 066 * @see TestExecutionListeners @TestExecutionListeners 067 * @see TestContextManager 068 * @see org.springframework.test.context.support.AbstractTestExecutionListener 069 */ 070public interface TestExecutionListener { 071 072 /** 073 * Pre-processes a test class <em>before</em> execution of all tests within 074 * the class. 075 * <p>This method should be called immediately before framework-specific 076 * <em>before class</em> lifecycle callbacks. 077 * <p>The default implementation is <em>empty</em>. Can be overridden by 078 * concrete classes as necessary. 079 * @param testContext the test context for the test; never {@code null} 080 * @throws Exception allows any exception to propagate 081 * @since 3.0 082 */ 083 default void beforeTestClass(TestContext testContext) throws Exception { 084 } 085 086 /** 087 * Prepares the {@link Object test instance} of the supplied 088 * {@link TestContext test context}, for example by injecting dependencies. 089 * <p>This method should be called immediately after instantiation of the test 090 * instance but prior to any framework-specific lifecycle callbacks. 091 * <p>The default implementation is <em>empty</em>. Can be overridden by 092 * concrete classes as necessary. 093 * @param testContext the test context for the test; never {@code null} 094 * @throws Exception allows any exception to propagate 095 */ 096 default void prepareTestInstance(TestContext testContext) throws Exception { 097 } 098 099 /** 100 * Pre-processes a test <em>before</em> execution of <em>before</em> 101 * lifecycle callbacks of the underlying test framework — for example, 102 * by setting up test fixtures. 103 * <p>This method <strong>must</strong> be called immediately prior to 104 * framework-specific <em>before</em> lifecycle callbacks. For historical 105 * reasons, this method is named {@code beforeTestMethod}. Since the 106 * introduction of {@link #beforeTestExecution}, a more suitable name for 107 * this method might be something like {@code beforeTestSetUp} or 108 * {@code beforeEach}; however, it is unfortunately impossible to rename 109 * this method due to backward compatibility concerns. 110 * <p>The default implementation is <em>empty</em>. Can be overridden by 111 * concrete classes as necessary. 112 * @param testContext the test context in which the test method will be 113 * executed; never {@code null} 114 * @throws Exception allows any exception to propagate 115 * @see #afterTestMethod 116 * @see #beforeTestExecution 117 * @see #afterTestExecution 118 */ 119 default void beforeTestMethod(TestContext testContext) throws Exception { 120 } 121 122 /** 123 * Pre-processes a test <em>immediately before</em> execution of the 124 * {@link java.lang.reflect.Method test method} in the supplied 125 * {@link TestContext test context} — for example, for timing 126 * or logging purposes. 127 * <p>This method <strong>must</strong> be called after framework-specific 128 * <em>before</em> lifecycle callbacks. 129 * <p>The default implementation is <em>empty</em>. Can be overridden by 130 * concrete classes as necessary. 131 * @param testContext the test context in which the test method will be 132 * executed; never {@code null} 133 * @throws Exception allows any exception to propagate 134 * @since 5.0 135 * @see #beforeTestMethod 136 * @see #afterTestMethod 137 * @see #afterTestExecution 138 */ 139 default void beforeTestExecution(TestContext testContext) throws Exception { 140 } 141 142 /** 143 * Post-processes a test <em>immediately after</em> execution of the 144 * {@link java.lang.reflect.Method test method} in the supplied 145 * {@link TestContext test context} — for example, for timing 146 * or logging purposes. 147 * <p>This method <strong>must</strong> be called before framework-specific 148 * <em>after</em> lifecycle callbacks. 149 * <p>The default implementation is <em>empty</em>. Can be overridden by 150 * concrete classes as necessary. 151 * @param testContext the test context in which the test method will be 152 * executed; never {@code null} 153 * @throws Exception allows any exception to propagate 154 * @since 5.0 155 * @see #beforeTestMethod 156 * @see #afterTestMethod 157 * @see #beforeTestExecution 158 */ 159 default void afterTestExecution(TestContext testContext) throws Exception { 160 } 161 162 /** 163 * Post-processes a test <em>after</em> execution of <em>after</em> 164 * lifecycle callbacks of the underlying test framework — for example, 165 * by tearing down test fixtures. 166 * <p>This method <strong>must</strong> be called immediately after 167 * framework-specific <em>after</em> lifecycle callbacks. For historical 168 * reasons, this method is named {@code afterTestMethod}. Since the 169 * introduction of {@link #afterTestExecution}, a more suitable name for 170 * this method might be something like {@code afterTestTearDown} or 171 * {@code afterEach}; however, it is unfortunately impossible to rename 172 * this method due to backward compatibility concerns. 173 * <p>The default implementation is <em>empty</em>. Can be overridden by 174 * concrete classes as necessary. 175 * @param testContext the test context in which the test method was 176 * executed; never {@code null} 177 * @throws Exception allows any exception to propagate 178 * @see #beforeTestMethod 179 * @see #beforeTestExecution 180 * @see #afterTestExecution 181 */ 182 default void afterTestMethod(TestContext testContext) throws Exception { 183 } 184 185 /** 186 * Post-processes a test class <em>after</em> execution of all tests within 187 * the class. 188 * <p>This method should be called immediately after framework-specific 189 * <em>after class</em> lifecycle callbacks. 190 * <p>The default implementation is <em>empty</em>. Can be overridden by 191 * concrete classes as necessary. 192 * @param testContext the test context for the test; never {@code null} 193 * @throws Exception allows any exception to propagate 194 * @since 3.0 195 */ 196 default void afterTestClass(TestContext testContext) throws Exception { 197 } 198 199}