Interface TestDistributionExtension


  • public interface TestDistributionExtension
    Task extension for configuring test distribution.

    This extension is added with name "distribution" to all Test tasks.

    Please refer to the user manual for details.

    • Field Detail

      • NAME

        static final java.lang.String NAME
        The name of the extension added to each test task.
        See Also:
        Constant Field Values
    • Method Detail

      • getEnabled

        @Internal
        Property<java.lang.Boolean> getEnabled()
        Whether test distribution is enabled.

        This setting defaults to false.

        Returns:
        whether test distribution is enabled
      • getMaxLocalExecutors

        @Internal
        Property<java.lang.Integer> getMaxLocalExecutors()
        The number of executors to use for running tests on this machine.

        This setting defaults to maxParallelForks. The number of local executors that can be used is limited by maxWorkerCount. Setting this to 0 causes tests to be only executed on the remote test execution infrastructure.

        Returns:
        the number of local executors to use.
      • getMaxRemoteExecutors

        @Internal
        Property<java.lang.Integer> getMaxRemoteExecutors()
        The number of remote executors that should be requested from the remote test execution infrastructure in order run the tests of this test task.

        This setting has no default value meaning that as much remote executors as are possible should be requested. Setting this to zero causes tests to be only executed using local executors.

        Note that setting this to a fixed number doesn't necessarily mean that this test task will get that many remote executors. It's just an indicator for the remote test execution infrastructure for how many executors it should try to make available to this test task. It may well be that this test task does not get any remote executors at all e.g. if no executors matching all requirements become available.

        Returns:
        the number of remote executors to request.
      • getRemoteExecutionPreferred

        @Internal
        Property<java.lang.Boolean> getRemoteExecutionPreferred()
        If enabled, remote executors are tried first, falling back to local ones after waitTimeout expires.

        This setting defaults to false.

        Returns:
        whether remote executors should be preferred over local executors
      • getWaitTimeout

        @Internal
        Property<java.time.Duration> getWaitTimeout()
        The duration the build waits for the remote test execution infrastructure to respond.

        This setting defaults to 30 seconds and must be set to a positive value.

        Returns:
        the wait timeout duration.
        Since:
        1.2
      • getRetryInSameJvm

        @Internal
        Property<java.lang.Boolean> getRetryInSameJvm()
        If enabled, the tests will be retried in the same JVM.

        This setting defaults to true.

        Returns:
        whether to retry tests in the same JVM
        Since:
        2.2.1
      • getRequirements

        @Input
        SetProperty<java.lang.String> getRequirements()
        The requirements that need to be fulfilled by executors in order to execute the tests of this test task.

        Requirements are matched against the capabilities of the connected remote executors. Only those executors having all required capabilities will be assigned for running the tests of this task. Local executors are assumed to provide any capabilities. This means that no matter the requirements, local executors will always be used as long as maxLocalExecutors is greater than 0.

        A requirement String may only contain alphanumeric characters, dashes, underscores, periods, and a single equals sign. Apart from that, users are free in how they want to structure requirements. The recommendation is to use key value pairs or tag-like requirements:

         test {
             distribution {
                 requirements = ['os=linux', 'db=mysql', 'EXECUTOR_POOL_1']
             }
         }
         

        The requirements will always have the value jdk=<version> added with <version> being derived from the executable set on this test task via Test.getExecutable().

        Returns:
        the requirements remote executors need to fulfill for running tests of this test task.
      • getFallbackToRegularExecutionOnMissingJUnitPlatform

        @Internal
        Property<java.lang.Boolean> getFallbackToRegularExecutionOnMissingJUnitPlatform()