/*
 * Copyright 2021 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.gradle.api.plugins.jvm;

import org.gradle.api.Action;
import org.gradle.api.Buildable;
import org.gradle.api.ExtensiblePolymorphicDomainObjectContainer;
import org.gradle.api.Incubating;
import org.gradle.api.tasks.SourceSet;
import org.gradle.testing.base.TestSuite;

/**
 * A group of related tests which both distinguish tests used for different purposes and which
 * can be configured to run against repeatedly against multiple {@link JvmTestSuiteTarget}s.
 *
 * @since 7.3
 */
@Incubating
public interface JvmTestSuite extends TestSuite, Buildable {
    /**
     * Returns the {@link SourceSet} containing tests for this suite.
     * @return the {@link SourceSet} containing tests for this suite.
     */
    SourceSet getSources();

    /**
     * Configures the {@link SourceSet} containing tests for this suite.
     * @param sourceSet an action to execute against the {@link SourceSet}
     */
    void sources(Action<? super SourceSet> sourceSet);

    /**
     * Returns the container of {@link JvmTestSuiteTarget} objects part of this suite.
     * @return the container of {@link JvmTestSuiteTarget} objects part of this suite.
     */
    ExtensiblePolymorphicDomainObjectContainer<? extends JvmTestSuiteTarget> getTargets();

    /**
     * Configures this suite to use the JUnit Jupiter platform libraries.  Defaults to version {@code 5.7.1}
     */
    void useJUnitJupiter();

    /**
     * Configures this suite to use the JUnit Jupiter platform libraries.
     * @param version the version of JUnit Jupiter platform to use, ex. {@code 5.7.1}
     */
    void useJUnitJupiter(String version);

    /**
     * Configures this suite to use JUnit 4 libraries.  Defaults to version {@code 4.13}
     */
    void useJUnit();

    /**
     * Configures this suite to use JUnit 4 libraries.
     * @param version the version of JUnit 4 to use, ex. {@code 4.13}
     */
    void useJUnit(String version);

    /**
     * Configures this suite to use the Spock Framework for testing.  Defaults to version {@code 2.0-groovy-3.0}
     */
    void useSpock();

    /**
     * Configures this suite to use the Spock Framework for testing.
     * @param version the version of Spock to use, ex. {@code 2.0-groovy-3.0}
     */
    void useSpock(String version);

    /**
     * Configures this suite to use the kotlin.test library for testing.
     */
    void useKotlinTest();

    /**
     * Configures this suite to use the kotlin.test library for testing.
     * @param version the version of kotlin.test to use, ex. {@code 1.5.31}
     */
    void useKotlinTest(String version);

    /**
     * Returns the container for any dependencies needed to compile and run a {@link JvmTestSuite}.
     * @return the container for any dependencies needed to compile and run a {@link JvmTestSuite}.
     */
    ComponentDependencies getDependencies();

    /**
     * Configures the container for any dependencies needed to compile and run a {@link JvmTestSuite}.
     * @param dependencies an action to execute against the container
     */
    void dependencies(Action<? super ComponentDependencies> dependencies);
}

@@ -2582,32 +2582,70 @@
 uite to use the 
+%3Ca href=%22https://spockframework.org/%22%3E
 Spock Framework 
@@ -2635,32 +2635,36 @@
 %3ESpock Framework
+%3C/a%3E
  for testing.  D
@@ -2783,16 +2783,54 @@
 use the 
+%3Ca href=%22https://spockframework.org/%22%3E
 Spock Fr
@@ -2836,16 +2836,20 @@
 ramework
+%3C/a%3E
  for tes
@@ -3020,35 +3020,96 @@
  to use the 
-kotlin.test
+%3Ca href=%22https://kotlinlang.org/api/latest/kotlin.test/%22%3Ekotlin.test%3C/a%3E
  library for
@@ -3201,27 +3201,88 @@
 use the 
-kotlin.test
+%3Ca href=%22https://kotlinlang.org/api/latest/kotlin.test/%22%3Ekotlin.test%3C/a%3E
  library

Add links to Spock and kotlin.test websites.