https://github.com/mirko-felice/gradle-plugin-testkit
Testing library to help users test gradle plugins.
https://github.com/mirko-felice/gradle-plugin-testkit
gradle-plugin testing testkit
Last synced: 8 months ago
JSON representation
Testing library to help users test gradle plugins.
- Host: GitHub
- URL: https://github.com/mirko-felice/gradle-plugin-testkit
- Owner: mirko-felice
- License: mit
- Created: 2023-04-29T09:27:28.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2025-08-21T23:54:58.000Z (9 months ago)
- Last Synced: 2025-08-22T01:28:55.328Z (9 months ago)
- Topics: gradle-plugin, testing, testkit
- Language: Kotlin
- Homepage:
- Size: 627 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Gradle Plugin Testkit
### Code Quality
[](https://github.com/mirko-felice/gradle-plugin-testkit/actions/workflows/ci-and-cd.yml)
[](https://sonarcloud.io/summary/overall?id=mirko-felice_gradle-plugin-testkit)
[](https://sonarcloud.io/summary/overall?id=mirko-felice_gradle-plugin-testkit)
[](https://sonarcloud.io/summary/overall?id=mirko-felice_gradle-plugin-testkit)
[](https://codecov.io/gh/mirko-felice/gradle-plugin-testkit)
### Modules
[](https://central.sonatype.com/artifact/io.github.mirko-felice.testkit/core)
[](https://plugins.gradle.org/plugin/io.github.mirko-felice.testkit)
#### Relative docs
[](https://javadoc.io/doc/io.github.mirko-felice.testkit/core)
[](https://javadoc.io/doc/io.github.mirko-felice.testkit/gradle-plugin)
## 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`](https://github.com/mirko-felice/gradle-plugin-testkit/blob/master/core/src/main/kotlin/io/github/mirkofelice/api/Testkit.kt).
It can be used in your own tests like below.
```kotlin
class ExampleTest : StringSpec({
"Example Test" {
Testkit.test(projectName)
}
})
```
It uses **_yaml_** files to declare the tests. More info [below](#yaml-structure).
It uses a [`CheckerType`](https://github.com/mirko-felice/gradle-plugin-testkit/blob/master/src/main/kotlin/io/github/mirkofelice/api/CheckerType.kt)
to know which subclass of [`TestkitChecker`](https://github.com/mirko-felice/gradle-plugin-testkit/blob/master/core/src/main/kotlin/io/github/mirkofelice/checkers/TestkitChecker.kt)
use to apply the various checks.
At the moment the project provides these types of checker:
- **KOTLIN**: refers to the [`KotlinChecker`](https://github.com/mirko-felice/gradle-plugin-testkit/blob/master/core/src/main/kotlin/io/github/mirkofelice/checkers/KotlinChecker.kt)
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.
```yaml
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
[](https://shorturl.at/fsTU4)
[](https://shorturl.at/qEHLY)
## 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`.
```kotlin
plugins {
id("io.github.mirko-felice.testkit") version ""
}
```
If not already applied, this plugin automatically applies [`java-gradle-plugin`](https://docs.gradle.org/current/userguide/java_gradle_plugin.html).
#### Configuration
To configure the plugin you can use the extension like below.
```kotlin
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
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fmirko-felice%2Fgradle-plugin-testkit-core)
Licensed under the [MIT License](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 , licensed
under an Artistic-2.0
- `glob`'s logo created by Tanya Brassie , licensed
under a Creative Commons Attribution-ShareAlike 4.0 International License
with copyright notice ->
'Copyright (c) 2009-2022 Isaac Z. Schlueter and Contributors'
- `spdx-exceptions` created by Kyle E. Mitchell , licensed
under a Creative Commons Attribution 3.0
- `diff` uses [IPA Font License](licenses/IPA%20Font%20License%20(IPA))