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 org.junit.jupiter.api.extension.ExtendWith;
019
020import java.lang.annotation.Retention;
021import java.lang.annotation.Target;
022
023import static java.lang.annotation.ElementType.TYPE;
024import static java.lang.annotation.RetentionPolicy.RUNTIME;
025
026/**
027 * JUnit 5 annotation that enables and controls the generator subsystem for test cases.
028 * This annotation provides reproducible test data generation by managing generator seeds
029 * and providing detailed failure information for test reproduction.
030 *
031 * <h2>Features</h2>
032 * <ul>
033 *   <li>Controls generator seed initialization</li>
034 *   <li>Provides detailed failure information for test reproduction</li>
035 *   <li>Supports fixed seeds via {@link GeneratorSeed} annotation</li>
036 *   <li>Enables system property configuration for seeds</li>
037 * </ul>
038 *
039 * <h2>Usage</h2>
040 * <pre>
041 * {@code
042 * @EnableGeneratorController
043 * class MyGeneratorTest {
044 *     @Test
045 *     void shouldGenerateData() {
046 *         var generator = new CollectionGenerator&lt;&gt;(Generators.strings());
047 *         var result = generator.list(5);
048 *         assertThat(result).hasSize(5);
049 *     }
050 * }
051 * }
052 * </pre>
053 *
054 * <h2>Test Reproduction</h2>
055 * On test failure, the extension provides detailed information about the generator seed:
056 * <pre>
057 * GeneratorController seed was 4711L.
058 * Use a fixed seed by applying @GeneratorSeed(4711L) for the method/class,
059 * or by using the system property '-Dde.cuioss.test.generator.seed=4711'
060 * </pre>
061 *
062 * <h2>Seed Configuration Options</h2>
063 * <ol>
064 *   <li>Method-level: {@code @GeneratorSeed(4711L)}</li>
065 *   <li>Class-level: {@code @GeneratorSeed(4711L)}</li>
066 *   <li>System Property: {@code -Dde.cuioss.test.generator.seed=4711}</li>
067 * </ol>
068 *
069 * @author Oliver Wolff
070 * @see GeneratorControllerExtension
071 * @see GeneratorSeed
072 */
073@Retention(RUNTIME)
074@Target(TYPE)
075@ExtendWith(GeneratorControllerExtension.class)
076public @interface EnableGeneratorController {
077
078}