org.springframework.test.context.TestContextBootstrapper Maven / Gradle / Ivy
Show all versions of spring-test Show documentation
/*
* Copyright 2002-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.test.context;
import java.util.List;
/**
* {@code TestContextBootstrapper} defines the SPI for bootstrapping the
* Spring TestContext Framework.
*
* A {@code TestContextBootstrapper} is used by the {@link TestContextManager} to
* {@linkplain #getTestExecutionListeners get the TestExecutionListeners} for the
* current test and to {@linkplain #buildTestContext build the TestContext} that
* it manages.
*
*
Configuration
*
* A custom bootstrapping strategy can be configured for a test class (or
* test class hierarchy) via {@link BootstrapWith @BootstrapWith}, either
* directly or as a meta-annotation.
*
*
If a bootstrapper is not explicitly configured via {@code @BootstrapWith},
* either the {@link org.springframework.test.context.support.DefaultTestContextBootstrapper
* DefaultTestContextBootstrapper} or the
* {@link org.springframework.test.context.web.WebTestContextBootstrapper
* WebTestContextBootstrapper} will be used, depending on the presence of
* {@link org.springframework.test.context.web.WebAppConfiguration @WebAppConfiguration}.
*
*
Implementation Notes
*
* Concrete implementations must provide a {@code public} no-args constructor.
*
*
WARNING: this SPI will likely change in the future in
* order to accommodate new requirements. Implementers are therefore strongly encouraged
* not to implement this interface directly but rather to extend
* {@link org.springframework.test.context.support.AbstractTestContextBootstrapper
* AbstractTestContextBootstrapper} or one of its concrete subclasses instead.
*
* @author Sam Brannen
* @since 4.1
* @see BootstrapWith
* @see BootstrapContext
*/
public interface TestContextBootstrapper {
/**
* Set the {@link BootstrapContext} to be used by this bootstrapper.
*/
void setBootstrapContext(BootstrapContext bootstrapContext);
/**
* Get the {@link BootstrapContext} associated with this bootstrapper.
*/
BootstrapContext getBootstrapContext();
/**
* Build the {@link TestContext} for the {@link BootstrapContext}
* associated with this bootstrapper.
* @return a new {@link TestContext}, never {@code null}
* @since 4.2
* @see #buildMergedContextConfiguration()
*/
TestContext buildTestContext();
/**
* Build the {@linkplain MergedContextConfiguration merged context configuration}
* for the test class in the {@link BootstrapContext} associated with this
* bootstrapper.
*
Implementations must take the following into account when building the
* merged configuration:
*
* - Context hierarchies declared via {@link ContextHierarchy @ContextHierarchy}
* and {@link ContextConfiguration @ContextConfiguration}
* - Active bean definition profiles declared via {@link ActiveProfiles @ActiveProfiles}
* - {@linkplain org.springframework.context.ApplicationContextInitializer
* Context initializers} declared via {@link ContextConfiguration#initializers}
* - Test property sources declared via {@link TestPropertySource @TestPropertySource}
*
* Consult the Javadoc for the aforementioned annotations for details on
* the required semantics.
*
Note that the implementation of {@link #buildTestContext()} should
* typically delegate to this method when constructing the {@code TestContext}.
*
When determining which {@link ContextLoader} to use for a given test
* class, the following algorithm should be used:
*
* - If a {@code ContextLoader} class has been explicitly declared via
* {@link ContextConfiguration#loader}, use it.
* - Otherwise, concrete implementations are free to determine which
* {@code ContextLoader} class to use as a default.
*
* @return the merged context configuration, never {@code null}
* @see #buildTestContext()
*/
MergedContextConfiguration buildMergedContextConfiguration();
/**
* Get a list of newly instantiated {@link TestExecutionListener TestExecutionListeners}
* for the test class in the {@link BootstrapContext} associated with this bootstrapper.
* If {@link TestExecutionListeners @TestExecutionListeners} is not
* present on the test class in the {@code BootstrapContext},
* default listeners should be returned. Furthermore, default
* listeners must be sorted using
* {@link org.springframework.core.annotation.AnnotationAwareOrderComparator
* AnnotationAwareOrderComparator}.
*
Concrete implementations are free to determine what comprises the
* set of default listeners. However, by default, the Spring TestContext
* Framework will use the
* {@link org.springframework.core.io.support.SpringFactoriesLoader SpringFactoriesLoader}
* mechanism to look up all {@code TestExecutionListener} class names
* configured in all {@code META-INF/spring.factories} files on the classpath.
*
The {@link TestExecutionListeners#inheritListeners() inheritListeners}
* flag of {@link TestExecutionListeners @TestExecutionListeners} must be
* taken into consideration. Specifically, if the {@code inheritListeners}
* flag is set to {@code true}, listeners declared for a given test class must
* be appended to the end of the list of listeners declared in superclasses.
* @return a list of {@code TestExecutionListener} instances
*/
List getTestExecutionListeners();
}