001package de.cuioss.test.jsf.junit5;
002
003import static java.lang.annotation.ElementType.TYPE;
004import static java.lang.annotation.RetentionPolicy.RUNTIME;
005
006import java.lang.annotation.Documented;
007import java.lang.annotation.Repeatable;
008import java.lang.annotation.Retention;
009import java.lang.annotation.Target;
010
011import javax.faces.context.FacesContext;
012
013import org.junit.jupiter.api.extension.ExtendWith;
014
015import de.cuioss.test.jsf.config.ApplicationConfigurator;
016import de.cuioss.test.jsf.config.BeanConfigurator;
017import de.cuioss.test.jsf.config.ComponentConfigurator;
018import de.cuioss.test.jsf.config.JsfTestConfiguration;
019import de.cuioss.test.jsf.config.RequestConfigurator;
020import de.cuioss.test.jsf.util.JsfEnvironmentHolder;
021import de.cuioss.test.valueobjects.util.IdentityResourceBundle;
022
023/**
024 * Using this annotations at type-level of a junit 5 test enable the
025 * myfaces-test-based test-framework for unit-tests. The configuration is
026 * implemented using some kind of decorator pattern (roughly). The actual
027 * configuration relies on two sources:
028 * <ul>
029 * <li>It scans for the annotations of type {@link JsfTestConfiguration}
030 * instantiates the corresponding classes and configures the environment
031 * accordingly</li>
032 * <li>It checks whether the actual test-class implements one of
033 * {@link ApplicationConfigurator}, {@link BeanConfigurator},
034 * {@link RequestConfigurator} or {@link ComponentConfigurator} and calls the
035 * corresponding methods accordingly, <em>after</em> the configurator derived by
036 * the annotations</li>
037 * </ul>
038 * <h3>Using</h3>
039 * <p>
040 * Simple Sample: Use a preconfigured JSF-context for the test providing
041 * BasicApplicationConfiguration
042 * </p>
043 *
044 * <pre>
045 * <code>
046     &#64;EnableJsfEnvironment
047     &#64;JsfTestConfiguration(BasicApplicationConfiguration.class)
048     class JSFEnableTest {
049</code>
050 * </pre>
051 *
052 * <p>
053 * Complex Sample: Use a preconfigured JSF-context with access to the context
054 * information like {@link FacesContext}, {@link ComponentConfigurator}, ... as
055 * defined within {@link JsfEnvironmentHolder} With this setup you can
056 * programmatically access the element
057 * </p>
058 *
059 * <pre>
060 * <code>
061     &#64;EnableJsfEnvironment
062     &#64;JsfTestConfiguration(BasicApplicationConfiguration.class)
063     class JsfSetupExtensionTest implements JsfEnvironmentConsumer {
064
065        &#64;Setter
066        &#64;Getter
067        private JsfEnvironmentHolder environmentHolder;</code>
068 * </pre>
069 *
070 * <p>
071 * In addition there is a new way of dealing with localized messages for
072 * unit-tests. In essence there is the {@link IdentityResourceBundle}
073 * configured: This is helpful for tests where you want to ensure that a certain
074 * message key is used to create a message but do not want to test the actual
075 * ResourceBundle mechanism itself. It will always return the given key itself.
076 * As default this mechanism is active, you can change this by setting
077 * {@link #useIdentityResourceBundle()}. If it is active it is used as well for
078 * resolving the MessageBundle. In case of many annotations of
079 * {@link EnableJsfEnvironment} are in the type hierarchy, the one on the most
080 * concrete Type will be chosen, usually on the actual unit-test.
081 * </p>
082 *
083 * @author Oliver Wolff
084 *
085 */
086@Documented
087@Retention(RUNTIME)
088@Target(TYPE)
089@ExtendWith(JsfSetupExtension.class)
090@Repeatable(EnableJsfEnvironments.class)
091public @interface EnableJsfEnvironment {
092
093    /**
094     * @return boolean
095     */
096    boolean useIdentityResourceBundle() default true;
097
098}