001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.bct;
018
019import java.lang.annotation.*;
020
021import org.apache.juneau.commons.lang.*;
022import org.junit.jupiter.api.extension.*;
023
024/**
025 * Annotation for configuring BCT settings in JUnit 5 tests.
026 *
027 * <p>
028 * This annotation can be applied to test classes or test methods to automatically configure
029 * BCT settings before tests run and clear them after tests complete.
030 *
031 * <h5 class='section'>Example:</h5>
032 * <p class='bjava'>
033 *    <ja>@BctConfig</ja>(sortMaps=TriState.<jsf>TRUE</jsf>)
034 *    <jk>class</jk> MyTest {
035 *       <ja>@Test</ja>
036 *       <ja>@BctConfig</ja>(sortCollections=TriState.<jsf>TRUE</jsf>)
037 *       <jk>void</jk> testFoo() {
038 *          <jc>// sortMaps and sortCollections are both enabled</jc>
039 *       }
040 *    }
041 * </p>
042 *
043 * <p>
044 * Method-level annotations override class-level annotations.
045 */
046@Target({ElementType.TYPE, ElementType.METHOD})
047@Retention(RetentionPolicy.RUNTIME)
048@ExtendWith(BctConfigExtension.class)
049public @interface BctConfig {
050
051   /**
052    * Enable sorting of maps in BCT assertions.
053    *
054    * @return {@link TriState#TRUE} to enable map sorting, {@link TriState#FALSE} to disable,
055    *    or {@link TriState#UNSET} to inherit from class-level annotation.
056    */
057   TriState sortMaps() default TriState.UNSET;
058
059   /**
060    * Enable sorting of collections in BCT assertions.
061    *
062    * @return {@link TriState#TRUE} to enable collection sorting, {@link TriState#FALSE} to disable,
063    *    or {@link TriState#UNSET} to inherit from class-level annotation.
064    */
065   TriState sortCollections() default TriState.UNSET;
066
067   /**
068    * Custom bean converter class to use for BCT assertions.
069    *
070    * <p>
071    * If specified (not the default {@link BeanConverter}), the class will be instantiated using
072    * its no-arg constructor and set as the converter for the current thread.
073    *
074    * <h5 class='section'>Example:</h5>
075    * <p class='bjava'>
076    *    <ja>@BctConfiguration</ja>(beanConverter=MyCustomConverter.<jk>class</jk>)
077    *    <jk>class</jk> MyTest {
078    *       <ja>@Test</ja>
079    *       <jk>void</jk> testFoo() {
080    *          <jc>// Uses MyCustomConverter for all assertions</jc>
081    *       }
082    *    }
083    * </p>
084    *
085    * @return The bean converter class to instantiate and use, or {@link BeanConverter} to use the default.
086    */
087   Class<? extends BeanConverter> beanConverter() default BeanConverter.class;
088}
089