001/*
002 * Copyright © 2025 CUI-OpenSource-Software (info@cuioss.de)
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 *     http://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 */
016package de.cuioss.test.generator.junit.parameterized;
017
018import de.cuioss.test.generator.TypedGenerator;
019import org.junit.jupiter.params.provider.ArgumentsSource;
020
021import java.lang.annotation.Documented;
022import java.lang.annotation.ElementType;
023import java.lang.annotation.Retention;
024import java.lang.annotation.RetentionPolicy;
025import java.lang.annotation.Target;
026
027/**
028 * {@code @TypeGeneratorSource} is an {@link ArgumentsSource} that provides
029 * access to values from a {@link TypedGenerator} implementation for
030 * parameterized tests.
031 * 
032 * <p>
033 * This annotation allows you to use any {@link TypedGenerator} implementation
034 * directly in your parameterized tests. The generator will be instantiated using
035 * its default constructor, and the specified number of values will be generated
036 * and passed to your test method.
037 * </p>
038 * 
039 * <h2>Example Usage</h2>
040 * 
041 * <pre>
042 * {@code
043 * @ParameterizedTest
044 * @TypeGeneratorSource(NonBlankStringGenerator.class)
045 * void testWithGeneratedStrings(String value) {
046 *     assertNotNull(value);
047 *     assertFalse(value.isBlank());
048 * }
049 * 
050 * @ParameterizedTest
051 * @TypeGeneratorSource(value = IntegerGenerator.class, count = 5)
052 * void testWithMultipleIntegers(Integer value) {
053 *     assertNotNull(value);
054 * }
055 * }
056 * </pre>
057 * 
058 * <p>
059 * If you need to use a custom generator with specific configuration, consider
060 * using {@code @TypeGeneratorMethodSource} instead.
061 * </p>
062 * 
063 * @author Oliver Wolff
064 * @since 2.0
065 * @see TypedGenerator
066 * @see TypeGeneratorArgumentsProvider
067 */
068@Target({ElementType.METHOD})
069@Retention(RetentionPolicy.RUNTIME)
070@Documented
071@ArgumentsSource(TypeGeneratorArgumentsProvider.class)
072public @interface TypeGeneratorSource {
073
074    /**
075     * The TypedGenerator class to use for generating test values.
076     * Must have a no-args constructor.
077     * 
078     * @return the TypedGenerator class
079     */
080    @SuppressWarnings("java:S1452") // owolff: This wildcard is because of the TypedGenerator interface. Ok for testing
081    Class<? extends TypedGenerator<?>> value();
082
083    /**
084     * Number of instances to generate.
085     * 
086     * @return the number of instances to generate, defaults to 1
087     */
088    int count() default 1;
089
090    /**
091     * Optional seed for reproducible tests.
092     * <p>
093     * If set to a value other than -1, this seed will be used for the generator
094     * instead of the seed managed by {@link de.cuioss.test.generator.junit.GeneratorControllerExtension}.
095     * </p>
096     * <p>
097     * This is useful for tests that need specific generated values regardless of
098     * the global seed configuration.
099     * </p>
100     * 
101     * @return the seed to use, or -1 to use the globally configured seed
102     */
103    long seed() default -1L;
104}