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.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Inherited;
022import java.lang.annotation.Retention;
023import java.lang.annotation.RetentionPolicy;
024import java.lang.annotation.Target;
025
026/**
027 * {@code @TestConstructor} is a type-level annotation that is used to configure
028 * how the parameters of a test class constructor are autowired from components
029 * in the test's {@link org.springframework.context.ApplicationContext
030 * ApplicationContext}.
031 *
032 * <p>If {@code @TestConstructor} is not <em>present</em> or <em>meta-present</em>
033 * on a test class, the default <em>test constructor autowire mode</em> will be
034 * used. See {@link #TEST_CONSTRUCTOR_AUTOWIRE_MODE_PROPERTY_NAME} for details on
035 * how to change the default mode. Note, however, that a local declaration of
036 * {@link org.springframework.beans.factory.annotation.Autowired @Autowired} on
037 * a constructor takes precedence over both {@code @TestConstructor} and the default
038 * mode.
039 *
040 * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
041 * <em>composed annotations</em>.
042 *
043 * <p>As of Spring Framework 5.2, this annotation is only supported in conjunction
044 * with the {@link org.springframework.test.context.junit.jupiter.SpringExtension
045 * SpringExtension} for use with JUnit Jupiter. Note that the {@code SpringExtension} is
046 * often automatically registered for you &mdash; for example, when using annotations such as
047 * {@link org.springframework.test.context.junit.jupiter.SpringJUnitConfig @SpringJUnitConfig} and
048 * {@link org.springframework.test.context.junit.jupiter.web.SpringJUnitWebConfig @SpringJUnitWebConfig}
049 * or various test-related annotations from Spring Boot Test.
050 *
051 * @author Sam Brannen
052 * @since 5.2
053 * @see org.springframework.beans.factory.annotation.Autowired @Autowired
054 * @see org.springframework.test.context.junit.jupiter.SpringExtension SpringExtension
055 * @see org.springframework.test.context.junit.jupiter.SpringJUnitConfig @SpringJUnitConfig
056 * @see org.springframework.test.context.junit.jupiter.web.SpringJUnitWebConfig @SpringJUnitWebConfig
057 * @see ContextConfiguration @ContextConfiguration
058 * @see ContextHierarchy @ContextHierarchy
059 * @see ActiveProfiles @ActiveProfiles
060 * @see TestPropertySource @TestPropertySource
061 */
062@Target(ElementType.TYPE)
063@Retention(RetentionPolicy.RUNTIME)
064@Documented
065@Inherited
066public @interface TestConstructor {
067
068        /**
069         * JVM system property used to change the default <em>test constructor
070         * autowire mode</em>: {@value #TEST_CONSTRUCTOR_AUTOWIRE_MODE_PROPERTY_NAME}.
071         * <p>Acceptable values include enum constants defined in {@link AutowireMode},
072         * ignoring case. For example, the default may be changed to {@link AutowireMode#ALL}
073         * by supplying the following JVM system property via the command line.
074         * <pre style="code">-Dspring.test.constructor.autowire.mode=all</pre>
075         * <p>If the property is not set to {@code ALL}, parameters for test class
076         * constructors will be autowired according to {@link AutowireMode#ANNOTATED}
077         * semantics by default.
078         * <p>May alternatively be configured via the
079         * {@link org.springframework.core.SpringProperties SpringProperties}
080         * mechanism.
081         * @see #autowireMode
082         */
083        String TEST_CONSTRUCTOR_AUTOWIRE_MODE_PROPERTY_NAME = "spring.test.constructor.autowire.mode";
084
085
086        /**
087         * Flag for setting the <em>test constructor {@linkplain AutowireMode autowire
088         * mode}</em> for the current test class.
089         * <p>Setting this flag overrides the global default. See
090         * {@link #TEST_CONSTRUCTOR_AUTOWIRE_MODE_PROPERTY_NAME} for details on how
091         * to change the global default.
092         * @return an {@link AutowireMode} to take precedence over the global default
093         * @see #TEST_CONSTRUCTOR_AUTOWIRE_MODE_PROPERTY_NAME
094         * @see org.springframework.beans.factory.annotation.Autowired @Autowired
095         * @see AutowireMode#ALL
096         * @see AutowireMode#ANNOTATED
097         */
098        AutowireMode autowireMode();
099
100
101        /**
102         * Defines autowiring modes for parameters in a test constructor.
103         * @see #ALL
104         * @see #ANNOTATED
105         */
106        enum AutowireMode {
107
108                /**
109                 * All test constructor parameters will be autowired as if the constructor
110                 * itself were annotated with
111                 * {@link org.springframework.beans.factory.annotation.Autowired @Autowired}.
112                 * @see #ANNOTATED
113                 */
114                ALL,
115
116                /**
117                 * Each individual test constructor parameter will only be autowired if it
118                 * is annotated with
119                 * {@link org.springframework.beans.factory.annotation.Autowired @Autowired},
120                 * {@link org.springframework.beans.factory.annotation.Qualifier @Qualifier},
121                 * or {@link org.springframework.beans.factory.annotation.Value @Value},
122                 * or if the constructor itself is annotated with {@code @Autowired}.
123                 * @see #ALL
124                 */
125                ANNOTATED;
126
127        }
128
129}