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
019import java.io.Serializable;
020import java.lang.reflect.Method;
021
022import org.springframework.context.ApplicationContext;
023import org.springframework.core.AttributeAccessor;
024import org.springframework.test.annotation.DirtiesContext.HierarchyMode;
025
026/**
027 * {@code TestContext} encapsulates the context in which a test is executed,
028 * agnostic of the actual testing framework in use.
029 *
030 * @author Sam Brannen
031 * @since 2.5
032 * @see TestContextManager
033 * @see TestExecutionListener
034 */
035public interface TestContext extends AttributeAccessor, Serializable {
036
037        /**
038         * Get the {@linkplain ApplicationContext application context} for this
039         * test context, possibly cached.
040         * <p>Implementations of this method are responsible for loading the
041         * application context if the corresponding context has not already been
042         * loaded, potentially caching the context as well.
043         * @return the application context (never {@code null})
044         * @throws IllegalStateException if an error occurs while retrieving the
045         * application context
046         */
047        ApplicationContext getApplicationContext();
048
049        /**
050         * Get the {@linkplain Class test class} for this test context.
051         * @return the test class (never {@code null})
052         */
053        Class<?> getTestClass();
054
055        /**
056         * Get the current {@linkplain Object test instance} for this test context.
057         * <p>Note: this is a mutable property.
058         * @return the current test instance (may be {@code null})
059         * @see #updateState(Object, Method, Throwable)
060         */
061        Object getTestInstance();
062
063        /**
064         * Get the current {@linkplain Method test method} for this test context.
065         * <p>Note: this is a mutable property.
066         * @return the current test method (may be {@code null})
067         * @see #updateState(Object, Method, Throwable)
068         */
069        Method getTestMethod();
070
071        /**
072         * Get the {@linkplain Throwable exception} that was thrown during execution
073         * of the {@linkplain #getTestMethod() test method}.
074         * <p>Note: this is a mutable property.
075         * @return the exception that was thrown, or {@code null} if no exception was thrown
076         * @see #updateState(Object, Method, Throwable)
077         */
078        Throwable getTestException();
079
080        /**
081         * Call this method to signal that the {@linkplain ApplicationContext application
082         * context} associated with this test context is <em>dirty</em> and should be
083         * removed from the context cache.
084         * <p>Do this if a test has modified the context &mdash; for example, by
085         * modifying the state of a singleton bean, modifying the state of an embedded
086         * database, etc.
087         * @param hierarchyMode the context cache clearing mode to be applied if the
088         * context is part of a hierarchy (may be {@code null})
089         */
090        void markApplicationContextDirty(HierarchyMode hierarchyMode);
091
092        /**
093         * Update this test context to reflect the state of the currently executing test.
094         * <p>Caution: concurrent invocations of this method might not be thread-safe,
095         * depending on the underlying implementation.
096         * @param testInstance the current test instance (may be {@code null})
097         * @param testMethod the current test method (may be {@code null})
098         * @param testException the exception that was thrown in the test method,
099         * or {@code null} if no exception was thrown
100         */
101        void updateState(Object testInstance, Method testMethod, Throwable testException);
102
103}