Core Suite Declaration

/**
 * Marks a class as a test suite on the JUnit Platform.
 * Selector and filter annotations control suite contents.
 * Configuration annotations provide suite-specific parameters.
 * 
 * Uses default include pattern when @IncludeClassNamePatterns not present:
 * "^(Test.*|.+[.$]Test.*|.*Tests?)$"
 * 
 * Inherits configuration parameters from discovery request unless disabled
 * with @DisableParentConfigurationParameters.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@Documented
@API(status = STABLE, since = "1.10")
@Testable
public @interface Suite {
    /**
     * Fail suite if no tests were discovered.
     * @return true to fail when no tests found, false to allow empty suites
     * @since 1.9
     */
    @API(status = STABLE, since = "1.11")
    boolean failIfNoTests() default true;
}

// Basic suite declaration
@Suite
@SelectClasses({TestA.class, TestB.class})
class BasicSuite {
}

// Suite allowing empty results
@Suite(failIfNoTests = false)
@SelectPackages("com.example.optional")
class OptionalSuite {
}

// Suite with multiple selection strategies
@Suite
@SelectClasses({CoreTest.class})
@SelectPackages("com.example.integration")
class CombinedSuite {
}

/**
 * Declares a custom display name for test suites.
 * Supports spaces, special characters, and emoji for enhanced readability.
 * Used by test reporting tools, IDEs, and build systems.
 * Overridden by @UseTechnicalNames when present (deprecated).
 * 
 * @since 1.1
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@Documented
@API(status = MAINTAINED)
public @interface SuiteDisplayName {
    /**
     * Custom display name for the test suite.
     * @return display name; never blank or containing only whitespace
     */
    String value();
}

@Suite
@SuiteDisplayName("Integration Test Suite")
@SelectPackages("com.example.integration")
class IntegrationSuite {
}

@Suite
@SuiteDisplayName("🚀 Performance Tests")
@SelectPackages("com.example.performance")
class PerformanceSuite {
}

@Suite  
@SuiteDisplayName("User Management - Complete Test Coverage")
@SelectClasses({UserServiceTest.class, UserRepositoryTest.class})
class UserManagementSuite {
}

/**
 * Use technical names instead of display names.
 * 
 * @deprecated Since 1.8, for removal in JUnit Platform 2.0.
 *             Superseded by native @Suite support.
 * @since 1.0
 */
@Deprecated
@API(status = DEPRECATED, since = "1.8", consumers = {"org.junit.platform.suite.engine"})
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
@Documented
public @interface UseTechnicalNames {
}

// Deprecated approach (avoid)
@Suite
@UseTechnicalNames
@SuiteDisplayName("My Suite")
class MySuite {
}

// Modern approach (recommended)
@Suite
@SelectClasses({TestA.class, TestB.class})
class MySuite {  // Technical name used automatically
}

@Suite
@SelectClasses({UserTest.class, ProductTest.class})
class BusinessLogicSuite {
}

@Suite
@SuiteDisplayName("End-to-End Integration Tests")
@SelectPackages("com.example.e2e")
class E2ESuite {
}

@Suite(failIfNoTests = false)
@SuiteDisplayName("Optional Component Tests")
@SelectPackages("com.example.optional")
@IncludeClassNamePatterns(".*ComponentTest")
class OptionalComponentSuite {
}

@Suite
@SuiteDisplayName("Comprehensive Test Coverage")
@SelectClasses({CoreBusinessTest.class})
@SelectPackages("com.example.integration")  
@SelectMethod(type = UtilityTest.class, name = "specialTest")
class ComprehensiveSuite {
}