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;
017
018import java.lang.annotation.Retention;
019import java.lang.annotation.Target;
020
021import static java.lang.annotation.ElementType.METHOD;
022import static java.lang.annotation.ElementType.TYPE;
023import static java.lang.annotation.RetentionPolicy.RUNTIME;
024
025/**
026 * Annotation for configuring fixed generator seeds in test cases.
027 * This annotation works in conjunction with {@link EnableGeneratorController}
028 * to provide reproducible test data generation.
029 *
030 * <h2>Features</h2>
031 * <ul>
032 *   <li>Can be applied at method or class level</li>
033 *   <li>Takes precedence over system property configuration</li>
034 *   <li>Ensures consistent test data across test runs</li>
035 *   <li>Useful for debugging and reproducing test failures</li>
036 * </ul>
037 *
038 * <h2>Usage Examples</h2>
039 * <pre>
040 * // Method-level configuration
041 * &#64;EnableGeneratorController
042 * class MyTest {
043 *     &#64;Test
044 *     &#64;GeneratorSeed(4711L)
045 *     void shouldGenerateConsistentData() {
046 *         var result = Generators.strings().next();
047 *         // Will always generate the same string
048 *     }
049 * }
050 *
051 * // Class-level configuration
052 * &#64;EnableGeneratorController
053 * &#64;GeneratorSeed(8042L)
054 * class MyReproducibleTest {
055 *     &#64;Test
056 *     void allTestsUseTheSameSeed() {
057 *         // All tests in this class use seed 8042L
058 *     }
059 * }
060 * </pre>
061 *
062 * <h2>Configuration Priority</h2>
063 * <ol>
064 *   <li>Method-level {@code @GeneratorSeed}</li>
065 *   <li>Class-level {@code @GeneratorSeed}</li>
066 *   <li>System property configuration</li>
067 * </ol>
068 *
069 * @author Oliver Wolff
070 * @see EnableGeneratorController
071 * @see GeneratorControllerExtension
072 */
073@Retention(RUNTIME)
074@Target({TYPE, METHOD})
075public @interface GeneratorSeed {
076
077    /**
078     * @return the seed for the generators
079     */
080    long value();
081}