Gradle Plugin Testkit

Code Quality

Modules

Relative docs

Core

Purpose

This library aims to help users to test own Gradle plugins, providing a declarative way to do that.

Usage

This library provides one main API: Testkit.

It can be used in your own tests like below.

class ExampleTest : StringSpec({
    
    "Example Test" {
        Testkit.test(projectName)
    }   
})

It uses yaml files to declare the tests. More info below.

It uses a CheckerType to know which subclass of TestkitChecker use to apply the various checks.

At the moment the project provides these types of checker:

• KOTLIN: refers to the KotlinChecker which uses the basic Kotlin assertions.

Configuration

The core function test() provides four parameters to give the user the capability to configure the feature.

• projectName: parameter describing the name of the project used to search for plugin classpath.

• projectFolderPath: parameter describing the path of the folder containing the yaml file. Default to currentDirectory/src/main/resources/.

• checkerType: parameter describing the CheckerType to use.
  Default to CheckerType.KOTLIN.

• forwardOutput: parameter describing if the user wants to see the Gradle build output or not.
  Default to false.

Yaml Structure

Yaml files have to be structured in a specific way.

Below there is a complete example.

tests:
  - description: "Example description"
    id: uniqueIdentifier
    requires: idOfAnotherTest
    configuration:
      tasks:
        - task1
        - task2
        - task3
      options:
        - option1
        - option2
    expectation:
      result: success
      outcomes:
        success:
          - successTask
        failed:
          - failedTask
        upToDate:
          - upToDateTask
        skipped:
          - skippedTask
        fromCache:
          - fromCacheTask
        noSource:
          - noSourceTask
        notExecuted:
          - notExecutedTask
      output:
        contains:
          - firstPartialOutput
          - secondPartialOutput
        doesntContain:
          - firstPartialOutput
          - secondPartialOutput
      files:
        existing:
          - name: "test.txt"
            content: "Example content"
            permissions:
              - R
              - W
              - X
            contentRegex: "$regex"

Class diagrams

Gradle-Plugin

Usage

To facilitate the user to use this library, a Gradle Plugin has been created.

Apply

In order to use the plugin, you should apply it in your build.gradle.kts.

plugins {
    id("io.github.mirko-felice.testkit") version "<x.y.z>"
}

If not already applied, this plugin automatically applies java-gradle-plugin.

Configuration

To configure the plugin you can use the extension like below.

testkit {
    checkerType.set(CheckerType.KOTLIN)
    forwardOutput.set(true)
    folders {
        withMainDefault()
        withTestDefault()
        projectFolder("path/to/yaml")
    }
    tests {
        folder = file("path/to/folder")
        test("description") {
            ...
        }
    }
}

The plugin provides a set of properties/methods, using two main DSL.

Required

No required property/method. That means no tests will be run.

Optional

Two main properties:

• checkerType: property describing the CheckerType to use for ALL tests.
  Default to CheckerType.KOTLIN.

• forwardOutput: property describing if the user wants to see the Gradle build output or not.
  Default to false.
  BE CAREFUL: even if this is set to true, you should run the task with the appropriate option -q, in order to get the output sorted correctly.
  Example: ./gradlew testkit -q

Using the folder DSL, folders can be added inside folders { } block:

• withMainDefault(): method to add the sub-folders into the default main path (src/main/resources).

• withTestDefault(): method to add the sub-folders into the default test path (src/test/resources).

• projectFolder(path: String): method to add a folder with the given path, always starting from the project directory.

• genericFolder(path: String): method to add a folder with the given path, can be located anywhere.

• subFoldersOfProject(path: String): method to add all the sub-folders in the given path, always starting from the project directory.

• subFoldersOf(path: String): method to add all the sub-folders in the given path, can be located anywhere.

These folders must contain the yaml file and the build.gradle.kts.

Using the test DSL, tests can be created inside tests { } block:

• folder: property to set the root folder containing the build.gradle.kts, always starting from the project directory.

• test(description: String) { }: method to add a new test with the given description, followed by its configuration. This provides a full DSL to mirror the yaml structure.

Tasks

This plugin creates the following tasks:

• testkitFolders: task able to run the testkit library using the folder DSL configuration.

• testkitDSL: task able to run the testkit library using the test DSL configuration.

• testkit: global task to execute all the testkit tasks.

License

Licensed under the MIT License.

License Compliance

This project uses npm to perform and does not modify its source code, so following authors' credits:

• npm created by The Perl Foundation https://www.perlfoundation.org/, licensed under an Artistic-2.0 https://opensource.org/licenses/Artistic-2.0
• glob's logo created by Tanya Brassie http://tanyabrassie.com/, licensed under a Creative Commons Attribution-ShareAlike 4.0 International License https://creativecommons.org/licenses/by-sa/4.0/ with copyright notice -> 'Copyright (c) 2009-2022 Isaac Z. Schlueter and Contributors'
• spdx-exceptions created by Kyle E. Mitchell https://kemitchell.com/, licensed under a Creative Commons Attribution 3.0 https://creativecommons.org/licenses/by/3.0/
• diff uses IPA Font License