Skip to content

Add: Kotlin configuration (kts) examples to readme #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 6, 2025
Merged

Add: Kotlin configuration (kts) examples to readme #115

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 157 additions & 62 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,33 @@ Apply the plugin to your top-level (root project) `build.gradle` file using one
following methods:

<details open>
<summary><strong>Plugin block:</strong></summary>
<summary><strong>Plugin block (Kotlin):</strong></summary>

```kotlin
plugins {
// Add the plugin to the plugin block
id("nl.neotech.plugin.rootcoverage") version "1.9.0"
}
```
</details>

<details>
<summary><strong>Plugin block (Groovy):</strong></summary>

```groovy
// Below buildscript {}
plugins {
id "nl.neotech.plugin.rootcoverage" version "1.9.0"
// Add the plugin to the plugin block
id "nl.neotech.plugin.rootcoverage" version "1.9.0"
}
```
</details>

<blockquote>

<details>
<summary><strong>classpath + apply:</strong></summary>
<summary><strong>Still using classpath & apply?</strong></summary>

**Groovy**
```groovy
apply plugin: 'nl.neotech.plugin.rootcoverage'

Expand All @@ -47,7 +61,7 @@ following methods:
}
```
</details>

</blockquote>

# 2. How to use

Expand All @@ -56,6 +70,28 @@ following methods:
modules that have at least one of these properties enabled in the final report (or individual
reports)

<details open>
<summary><strong>Kotlin</strong> (.gradle.kts)</summary>

```kotlin
android {
buildTypes {
debug {
// AGP 7.3+ (at least one should be true for this module to be included in the reporting)
enableUnitTestCoverage = true
enableAndroidTestCoverage = true

// AGP before 7.3
testCoverageEnabled = true
}
}
}
```
</details>

<details>
<summary><strong>Groovy</strong> (.gradle)</summary>

```groovy
android {
buildTypes {
Expand All @@ -70,6 +106,7 @@ following methods:
}
}
```
</details>

> Only Android modules (`com.android.application` or `com.android.library`) are supported, this plugin will not execute
tests and generate coverage reports for non-android modules. Also keep in mind that by default
Expand All @@ -93,86 +130,137 @@ module. However in some cases different build variants per module might be requi
there is no `debug` build variant available. In those cases you can configure custom build variants
for specific modules:

```groovy
rootCoverage {
// The default build variant for every module
buildVariant "debug"
// Overrides the default build variant for specific modules.
buildVariantOverrides ":moduleA" : "debugFlavourA", ":moduleB": "debugFlavourA"

// Class & package exclude patterns
excludes = ["**/some.package/**"]

// Since 1.1 generateHtml is by default true
generateCsv false
generateHtml true
generateXml false
>**Place this in the project root build.gradle file!**

// Since 1.2: Same as executeTests except that this only affects the instrumented Android tests
executeAndroidTests true

// Since 1.2: Same as executeTests except that this only affects the unit tests
executeUnitTests true
<details open>
<summary><strong>Kotlin</strong> (.gradle.kts)</summary>

```kotlin
rootCoverage {
// The default build variant for every module
buildVariant = "debug"
// Overrides the default build variant for specific modules.
buildVariantOverrides = mapOf(":moduleA" to "debugFlavourA", ":moduleB" to "debugFlavourA")

// Class & package exclude patterns
excludes = ["**/some.package/**"]

// Since 1.1 generateHtml is by default true
generateCsv = false
generateHtml = true
generateXml = false

// Since 1.2: Same as executeTests except that this only affects the instrumented Android tests
executeAndroidTests = true

// Since 1.2: Same as executeTests except that this only affects the unit tests
executeUnitTests = true

// Since 1.2: When true include results from instrumented Android tests into the coverage report
includeAndroidTestResults = true

// Since 1.2: When true include results from unit tests into the coverage report
includeUnitTestResults = true

// Since 1.4: Sets jacoco.includeNoLocationClasses, so you don't have to. Helpful when using Robolectric
// which usually requires this attribute to be true
includeNoLocationClasses = false

// Since 1.7 (experimental): If set to true instrumented tests will be attempt to run on
// Gradle Managed Devices before trying devices connected through other means (ADB).
runOnGradleManagedDevices = false

// Since 1.7 (experimental): The name of the Gradle Managed device to run instrumented tests on.
// This is only used if `runOnGradleManagedDevices` is set to true. If not given tests will be
// run on all available Gradle Managed Devices
gradleManagedDeviceName = "nexusoneapi30"
}
```
</details>

// Since 1.2: When true include results from instrumented Android tests into the coverage report
includeAndroidTestResults true
<details>
<summary><strong>Groovy</strong> (.gradle)</summary>

// Since 1.2: When true include results from unit tests into the coverage report
includeUnitTestResults true
```groovy
rootCoverage {
// The default build variant for every module
buildVariant "debug"
// Overrides the default build variant for specific modules.
buildVariantOverrides ":moduleA" : "debugFlavourA", ":moduleB": "debugFlavourA"

// Since 1.4: Sets jacoco.includeNoLocationClasses, so you don't have to. Helpful when using Robolectric
// which usually requires this attribute to be true
includeNoLocationClasses false

// Since 1.7 (experimental): If set to true instrumented tests will be attempt to run on
// Gradle Managed Devices before trying devices connected through other means (ADB).
runOnGradleManagedDevices false
// Class & package exclude patterns
excludes = ["**/some.package/**"]

// Since 1.7 (experimental): The name of the Gradle Managed device to run instrumented tests on.
// This is only used if `runOnGradleManagedDevices` is set to true. If not given tests will be
// run on all available Gradle Managed Devices
gradleManagedDeviceName "nexusoneapi30"
}
```

// Since 1.1 generateHtml is by default true
generateCsv false
generateHtml true
generateXml false

// Since 1.2: Same as executeTests except that this only affects the instrumented Android tests
executeAndroidTests true

// Since 1.2: Same as executeTests except that this only affects the unit tests
executeUnitTests true

// Since 1.2: When true include results from instrumented Android tests into the coverage report
includeAndroidTestResults true

// Since 1.2: When true include results from unit tests into the coverage report
includeUnitTestResults true

// Since 1.4: Sets jacoco.includeNoLocationClasses, so you don't have to. Helpful when using Robolectric
// which usually requires this attribute to be true
includeNoLocationClasses false

// Since 1.7 (experimental): If set to true instrumented tests will be attempt to run on
// Gradle Managed Devices before trying devices connected through other means (ADB).
runOnGradleManagedDevices false

// Since 1.7 (experimental): The name of the Gradle Managed device to run instrumented tests on.
// This is only used if `runOnGradleManagedDevices` is set to true. If not given tests will be
// run on all available Gradle Managed Devices
gradleManagedDeviceName "nexusoneapi30"
}
```
</details>

# 4. Compatibility
| Version | [Android Gradle plugin version](https://developer.android.com/studio/releases/gradle-plugin#updating-gradle) | Gradle version |
|------------|--------------------------------------------------------------------------------------------------------------|------------------------|
| **1.9.0** | 8.6.0 | 8.7+ |
| **1.9.0** | 8.6.0+ | 8.7+ |
| **1.8.0** | 8.5.2<br/>8.4.2<br/>8.3.0-alpha05 - 8.3.2 | 8.6+<br/>8.5+<br/>8.4+ |
| **Note 2** | 8.0 - 8.3.0-alpha04 | n.a. |
| **Note 1** | 8.0 - 8.3.0-alpha04 | n.a. |
| **1.7.1** | 7.4 | 7.5+ |
| **1.6.0** | 7.3 | 7.4+ |
| **1.5.3** | 7.2 | 7.3+ |
| **Note 3** | 7.0 - 7.2.0-alpha05 | n.a. |
| **Note 2** | 7.0 - 7.2.0-alpha05 | n.a. |
| **1.4.0** | 4.2<br/>4.1 | 6.7.1+<br/>6.5+ |
| **1.3.1** | 4.0<br/>3.6 | 6.1.1+<br/>5.6.4+ |
| **1.2.1** | 3.5 | 5.4.1+ |
| **1.1.2** | 3.4 | 5.1.1+ |
| **1.1.1** | 3.3 | 4.10.1+ |
| **1.0.2** | 3.2 | 4.6+ |

<details open>
<summary><b>Note 2: AGP 8.0-8.3.0-alpha04</b></summary>
<details>
<summary><b>Note 1: AGP 8.0-8.3.0-alpha04</b></summary>

*Android Gradle Plugin version 8.0 till 8.3.0-alpha04 suffered from a [bug](https://issuetracker.google.com/u/0/issues/281266702) that made it impossible (by normal means) to get access to non-instrumented class files, this bug lasted for a long time and was only fixed in 8.3.0-alpha05. This means there is no stable working plugin version available for these AGP versions.*
</details>

<details>
<summary><b>Note 3: AGP 7.0-7.2.0-alpha05</b></summary>
<summary><b>Note 2: AGP 7.0-7.2.0-alpha05</b></summary>

*Android Gradle Plugin version 7 till 7.2.0-alpha05 suffered from a [bug](https://issuetracker.google.com/issues/195860510) that caused instrumented coverage in Android library modules to fail, this has only been [fixed](https://github.com/NeoTech-Software/Android-Root-Coverage-Plugin/issues/36#issuecomment-977241070) in Android Gradle Plugin 7.2.0-alpha06. This means there is no stable working plugin version available for these AGP versions.*
</details>

<details>
<summary><b>Note 4: group ID change & Maven Central</b></summary>
<summary><b>Note 3: Versions 1.0.2 to 1.3.0</b></summary>

*Plugin versions below 1.3.1, such as 1.3.0, are only available on the Gradle Plugin Portal (`maven { url "https://plugins.gradle.org/m2/"}`) and not on Maven Central. These versions use the group ID `org.neotech.plugin` and plugin ID `org.neotech.plugin.rootcoverage`!*
*Plugin versions below 1.3.1, such as 1.3.0, are only available on the Gradle Plugin Portal and not on Maven Central. These versions use the group ID `org.neotech.plugin` and plugin ID `org.neotech.plugin.rootcoverage`! For more info see: [Bintray/JCenter shutdown](#4-bintrayjcenter-shutdown).*
</details>

<details>
<summary><b>Note 5: AGP versions before 3.4.0-alpha05</b></summary>
<summary><b>Note 4: AGP versions before 3.4.0-alpha05</b></summary>

*Android Gradle Plugin versions before `3.4.0-alpha05` are affected by a bug that in certain conditions can cause Jacoco instrumentation to fail in combination with inline kotlin methods shared across modules. For more information see: [issue #109771903](https://issuetracker.google.com/issues/109771903) and [issue #110763361](https://issuetracker.google.com/issues/110763361). If your project is affected by this upgrade to an Android Gradle Plugin version of at least `3.4.0-alpha05`.*
</details>
Expand All @@ -184,18 +272,25 @@ the Android-Root-Coverage-Plugin has been migrated to Sonatype's Maven Central r
meant that the group ID used by the Android-Root-Coverage-Plugin had to be changed from `org.neotech.plugin` to
`nl.neotech.plugin`. The plugin ID has also changed from `org.neotech.plugin.rootcoverage` to `nl.neotech.plugin.rootcoverage`.

JCenter is supposed to stay available as read-only repository, however it is probably better to migrate to
the Gradle Plugin Portal, since all version of this plugin are also available there:
```groovy
pluginManagement {
repositories {
gradlePluginPortal()
<details>
<summary><strong>More info</strong></summary>

JCenter is supposed to stay available as read-only repository, however it is probably better to
migrate to the Gradle Plugin Portal, as it is the official Gradle repository for plugins, and all
versions of this plugin are available there:
```groovy
pluginManagement {
repositories {
// Add this repository to your build script for plugin resolution, above mavenCentral() or jcenter()
gradlePluginPortal()
}
}
}
```
Version 1.3.0 has been re-released (as 1.3.1) with the new group ID and plugin ID to Maven Central and the
Gradle Plugin Portal. Upcoming versions will also be released to Maven Central and the Gradle Plugin Portal.
Check the [setup](#1-setup) section on how to use this plugin with the updated group ID and plugin ID.
```
Version 1.3.0 has been re-released (as 1.3.1) with the new group ID and plugin ID to Maven Central and the
Gradle Plugin Portal. Upcoming versions will also be released to Maven Central and the Gradle Plugin Portal.
Check the [setup](#1-setup) section on how to use this plugin with the updated group ID and plugin ID.

</details>


# 5. Development
Expand Down