001/*
002 * Copyright 2002-2016 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.util.List;
020
021/**
022 * {@code TestContextBootstrapper} defines the SPI for bootstrapping the
023 * <em>Spring TestContext Framework</em>.
024 *
025 * <p>A {@code TestContextBootstrapper} is used by the {@link TestContextManager} to
026 * {@linkplain #getTestExecutionListeners get the TestExecutionListeners} for the
027 * current test and to {@linkplain #buildTestContext build the TestContext} that
028 * it manages.
029 *
030 * <h3>Configuration</h3>
031 *
032 * <p>A custom bootstrapping strategy can be configured for a test class (or
033 * test class hierarchy) via {@link BootstrapWith @BootstrapWith}, either
034 * directly or as a meta-annotation.
035 *
036 * <p>If a bootstrapper is not explicitly configured via {@code @BootstrapWith},
037 * either the {@link org.springframework.test.context.support.DefaultTestContextBootstrapper
038 * DefaultTestContextBootstrapper} or the
039 * {@link org.springframework.test.context.web.WebTestContextBootstrapper
040 * WebTestContextBootstrapper} will be used, depending on the presence of
041 * {@link org.springframework.test.context.web.WebAppConfiguration @WebAppConfiguration}.
042 *
043 * <h3>Implementation Notes</h3>
044 *
045 * <p>Concrete implementations must provide a {@code public} no-args constructor.
046 *
047 * <p><strong>WARNING</strong>: this SPI will likely change in the future in
048 * order to accommodate new requirements. Implementers are therefore strongly encouraged
049 * <strong>not</strong> to implement this interface directly but rather to <em>extend</em>
050 * {@link org.springframework.test.context.support.AbstractTestContextBootstrapper
051 * AbstractTestContextBootstrapper} or one of its concrete subclasses instead.
052 *
053 * @author Sam Brannen
054 * @since 4.1
055 * @see BootstrapWith
056 * @see BootstrapContext
057 */
058public interface TestContextBootstrapper {
059
060        /**
061         * Set the {@link BootstrapContext} to be used by this bootstrapper.
062         */
063        void setBootstrapContext(BootstrapContext bootstrapContext);
064
065        /**
066         * Get the {@link BootstrapContext} associated with this bootstrapper.
067         */
068        BootstrapContext getBootstrapContext();
069
070        /**
071         * Build the {@link TestContext} for the {@link BootstrapContext}
072         * associated with this bootstrapper.
073         * @return a new {@link TestContext}, never {@code null}
074         * @since 4.2
075         * @see #buildMergedContextConfiguration()
076         */
077        TestContext buildTestContext();
078
079        /**
080         * Build the {@linkplain MergedContextConfiguration merged context configuration}
081         * for the test class in the {@link BootstrapContext} associated with this
082         * bootstrapper.
083         * <p>Implementations must take the following into account when building the
084         * merged configuration:
085         * <ul>
086         * <li>Context hierarchies declared via {@link ContextHierarchy @ContextHierarchy}
087         * and {@link ContextConfiguration @ContextConfiguration}</li>
088         * <li>Active bean definition profiles declared via {@link ActiveProfiles @ActiveProfiles}</li>
089         * <li>{@linkplain org.springframework.context.ApplicationContextInitializer
090         * Context initializers} declared via {@link ContextConfiguration#initializers}</li>
091         * <li>Test property sources declared via {@link TestPropertySource @TestPropertySource}</li>
092         * </ul>
093         * <p>Consult the Javadoc for the aforementioned annotations for details on
094         * the required semantics.
095         * <p>Note that the implementation of {@link #buildTestContext()} should
096         * typically delegate to this method when constructing the {@code TestContext}.
097         * <p>When determining which {@link ContextLoader} to use for a given test
098         * class, the following algorithm should be used:
099         * <ol>
100         * <li>If a {@code ContextLoader} class has been explicitly declared via
101         * {@link ContextConfiguration#loader}, use it.</li>
102         * <li>Otherwise, concrete implementations are free to determine which
103         * {@code ContextLoader} class to use as a default.</li>
104         * </ol>
105         * @return the merged context configuration, never {@code null}
106         * @see #buildTestContext()
107         */
108        MergedContextConfiguration buildMergedContextConfiguration();
109
110        /**
111         * Get a list of newly instantiated {@link TestExecutionListener TestExecutionListeners}
112         * for the test class in the {@link BootstrapContext} associated with this bootstrapper.
113         * <p>If {@link TestExecutionListeners @TestExecutionListeners} is not
114         * <em>present</em> on the test class in the {@code BootstrapContext},
115         * <em>default</em> listeners should be returned. Furthermore, default
116         * listeners must be sorted using
117         * {@link org.springframework.core.annotation.AnnotationAwareOrderComparator
118         * AnnotationAwareOrderComparator}.
119         * <p>Concrete implementations are free to determine what comprises the
120         * set of default listeners. However, by default, the Spring TestContext
121         * Framework will use the
122         * {@link org.springframework.core.io.support.SpringFactoriesLoader SpringFactoriesLoader}
123         * mechanism to look up all {@code TestExecutionListener} class names
124         * configured in all {@code META-INF/spring.factories} files on the classpath.
125         * <p>The {@link TestExecutionListeners#inheritListeners() inheritListeners}
126         * flag of {@link TestExecutionListeners @TestExecutionListeners} must be
127         * taken into consideration. Specifically, if the {@code inheritListeners}
128         * flag is set to {@code true}, listeners declared for a given test class must
129         * be appended to the end of the list of listeners declared in superclasses.
130         * @return a list of {@code TestExecutionListener} instances
131         */
132        List<TestExecutionListener> getTestExecutionListeners();
133
134}