Skip to content

Update utbot-gradle documentation #363

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 2 commits into from
Jun 30, 2022
Merged

Update utbot-gradle documentation #363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0663668
Update utbot-gradle documentation (#342)
mmvpm Jun 30, 2022
bcea447
Add publishing to the plugin portal to build.gradle (#342)
mmvpm Jun 30, 2022
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
61 changes: 54 additions & 7 deletions utbot-gradle/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,79 @@
plugins {
id 'java-gradle-plugin'
id 'com.gradle.plugin-publish' version '0.18.0'
id 'com.github.johnrengelman.shadow' version '6.1.0'
}

apply from: "${parent.projectDir}/gradle/include/jvm-project.gradle"

dependencies {
api project(":utbot-framework")
shadow gradleApi()
shadow localGroovy()

implementation project(":utbot-framework")

implementation group: 'io.github.microutils', name: 'kotlin-logging', version: kotlin_logging_version
}

// needed to prevent inclusion of gradle-api into shadow JAR
configurations.compile.dependencies.remove dependencies.gradleApi()

configurations.all {
exclude group: "org.apache.logging.log4j", module: "log4j-slf4j-impl"
}

gradlePlugin {
plugins {
sarifReportPlugin {
id = 'org.utbot.gradle.plugin'
implementationClass = 'org.utbot.gradle.plugin.SarifGradlePlugin'
}
jar {
manifest {
// 'Fat JAR' is needed in org.utbot.framework.codegen.model.util.DependencyUtilsKt.checkDependencyIsFatJar
attributes 'JAR-Type': 'Fat JAR'
attributes 'Class-Path': configurations.compile.collect { it.getName() }.join(' ')
}
}

shadowJar {
archiveClassifier.set('')
minimize()
}

// no module metadata => no dependency on the `utbot-framework`
tasks.withType(GenerateModuleMetadata) {
enabled = false
}

publishing {
publications {
pluginMaven(MavenPublication) {
pom.withXml {
// removing a dependency to `utbot-framework` from the list of dependencies
asNode().dependencies.dependency.each { dependency ->
if (dependency.artifactId[0].value()[0] == 'utbot-framework') {
assert dependency.parent().remove(dependency)
}
}
}
}
}
repositories {
maven {
url = layout.buildDirectory.dir('repo')
}
}
}

pluginBundle {
website = 'https://www.utbot.org/'
vcsUrl = 'https://github.com/UnitTestBot/UTBotJava/'
tags = ['java', 'unit-testing', 'tests-generation', 'sarif']
}

gradlePlugin {
plugins {
sarifReportPlugin {
version = '1.0.0-alpha-9' // last published version
id = 'org.utbot.gradle.plugin'
displayName = 'UnitTestBot gradle plugin'
description = 'The gradle plugin for generating tests and creating SARIF reports based on UnitTestBot'
implementationClass = 'org.utbot.gradle.plugin.SarifGradlePlugin'
}
}
}
234 changes: 94 additions & 140 deletions utbot-gradle/docs/utbot-gradle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,22 @@ In addition, it creates one big SARIF-report containing the results from all the

### How to use

_TODO: The plugin has not been published yet._
Please, check for the available versions [here](https://plugins.gradle.org/plugin/org.utbot.gradle.plugin).

- Apply the plugin:

<details>
<summary>Groovy</summary>
<pre>
apply plugin: 'org.utbot.gradle.plugin'
</pre>
</details>

<details>
<summary>Kotlin DSL</summary>
<pre>
apply(plugin = "org.utbot.gradle.plugin")
</pre>
</details>
__Groovy:__
```Groovy
plugins {
id "org.utbot.gradle.plugin" version "..."
}
```
__Kotlin DSL:__
```Kotlin
plugins {
id("org.utbot.gradle.plugin") version "..."
}
```

- Run gradle task `utbot/generateTestsAndSarifReport` to create a report.

Expand All @@ -33,48 +32,42 @@ _TODO: The plugin has not been published yet._

For example, the following configuration may be used:

<details>
<summary>Groovy</summary>
<pre>
sarifReport {
targetClasses = ['com.abc.Main', 'com.qwerty.Util']
projectRoot = 'C:/.../SomeDirectory'
generatedTestsRelativeRoot = 'build/generated/test'
sarifReportsRelativeRoot = 'build/generated/sarif'
markGeneratedTestsDirectoryAsTestSourcesRoot = true
testFramework = 'junit5'
mockFramework = 'mockito'
generationTimeout = 60000L
codegenLanguage = 'java'
mockStrategy = 'package-based'
staticsMocking = 'mock-statics'
forceStaticMocking = 'force'
classesToMockAlways = ['org.slf4j.Logger', 'java.util.Random']
}
</pre>
</details>


<details>
<summary>Kotlin DSL</summary>
<pre>
configure&lt;SarifGradleExtension&gt; {
targetClasses.set(listOf("com.abc.Main", "com.qwerty.Util"))
projectRoot.set("C:/.../SomeDirectory")
generatedTestsRelativeRoot.set("build/generated/test")
sarifReportsRelativeRoot.set("build/generated/sarif")
markGeneratedTestsDirectoryAsTestSourcesRoot.set(true)
testFramework.set("junit5")
mockFramework.set("mockito")
generationTimeout.set(60000L)
codegenLanguage.set("java")
mockStrategy.set("package-based")
staticsMocking.set("mock-statics")
forceStaticMocking.set("force")
classesToMockAlways.set(listOf("org.slf4j.Logger", "java.util.Random"))
}
</pre>
</details>
__Groovy:__
```Groovy
sarifReport {
targetClasses = ['com.abc.Main', 'com.qwerty.Util']
projectRoot = 'C:/.../SomeDirectory'
generatedTestsRelativeRoot = 'build/generated/test'
sarifReportsRelativeRoot = 'build/generated/sarif'
markGeneratedTestsDirectoryAsTestSourcesRoot = true
testFramework = 'junit5'
mockFramework = 'mockito'
generationTimeout = 60000L
codegenLanguage = 'java'
mockStrategy = 'package-based'
staticsMocking = 'mock-statics'
forceStaticMocking = 'force'
classesToMockAlways = ['org.slf4j.Logger', 'java.util.Random']
}
```
__Kotlin DSL:__
```Kotlin
configure<SarifGradleExtension> {
targetClasses.set(listOf("com.abc.Main", "com.qwerty.Util"))
projectRoot.set("C:/.../SomeDirectory")
generatedTestsRelativeRoot.set("build/generated/test")
sarifReportsRelativeRoot.set("build/generated/sarif")
markGeneratedTestsDirectoryAsTestSourcesRoot.set(true)
testFramework.set("junit5")
mockFramework.set("mockito")
generationTimeout.set(60000L)
codegenLanguage.set("java")
mockStrategy.set("package-based")
staticsMocking.set("mock-statics")
forceStaticMocking.set("force")
classesToMockAlways.set(listOf("org.slf4j.Logger", "java.util.Random"))
}
```

**Note:** All configuration fields have default values, so there is no need to configure the plugin if you don't want to.

Expand Down Expand Up @@ -151,94 +144,45 @@ configure&lt;SarifGradleExtension&gt; {

If you want to change the source code of the plugin or even the whole utbot-project,
you need to do the following:
- Publish the modified project to the local maven repository
- Correctly specify the dependencies in the build file (in your project)
- Apply the plugin (see the section __How to use__).

There are two ways to do it.

- **The first way**
- Run `publishing/publishToMavenLocal` (**utbot root** gradle task)

- Add to your build file:

<details>
<summary>Groovy</summary>
<pre>
buildscript {
repositories {
mavenLocal()
mavenCentral()
maven { url 'https://jitpack.io' }
}
&nbsp;
dependencies {
classpath group: 'org.utbot', name: 'utbot-gradle', version: '1.0-SNAPSHOT'
}

- Publish plugin to the local maven repository:
`utbot-gradle/publishing/publishToMavenLocal`

- Add to your build file:

__Groovy:__
```Groovy
buildscript {
repositories {
mavenLocal()
}
</pre>
</details>

<details>
<summary>Kotlin DSL</summary>
<pre>
buildscript {
repositories {
mavenLocal()
mavenCentral()
maven { url 'https://jitpack.io' }
}
&nbsp;
dependencies {
classpath("org.utbot:utbot-gradle:1.0-SNAPSHOT")
}
dependencies {
classpath "org.utbot:utbot-gradle:1.0-SNAPSHOT"
}
</pre>
</details>

- **The second way** (faster, but more difficult)
- Run `publishing/publishToMavenLocal` (**utbot-gradle** gradle task)
- Add to your `build.gradle`:

<details>
<summary>Groovy</summary>
<pre>
buildscript {
repositories {
mavenLocal()
mavenCentral()
maven { url 'https://jitpack.io' }
}
&nbsp;
dependencies {
classpath group: 'org.utbot', name: 'utbot-gradle', version: '1.0-SNAPSHOT'
classpath files('C:/..[your-path]../UTBotJava/utbot-framework/build/libs/utbot-framework-1.0-SNAPSHOT.jar')
classpath files('C:/..[your-path]../UTBotJava/utbot-framework-api/build/libs/utbot-framework-api-1.0-SNAPSHOT.jar')
classpath files('C:/..[your-path]../UTBotJava/utbot-instrumentation/build/libs/utbot-instrumentation-1.0-SNAPSHOT.jar')
}
}
```
__Kotlin DSL:__
```Kotlin
buildscript {
repositories {
mavenLocal()
}
</pre>
</details>

<details>
<summary>Kotlin DSL</summary>
<pre>
buildscript {
repositories {
mavenLocal()
mavenCentral()
maven { url 'https://jitpack.io' }
}
&nbsp;
dependencies {
classpath("org.utbot:utbot-gradle:1.0-SNAPSHOT")
classpath(files("C:/..[your-path]../UTBotJava/utbot-framework/build/libs/utbot-framework-1.0-SNAPSHOT.jar"))
classpath(files("C:/..[your-path]../UTBotJava/utbot-framework-api/build/libs/utbot-framework-api-1.0-SNAPSHOT.jar"))
classpath(files("C:/..[your-path]../UTBotJava/utbot-instrumentation/build/libs/utbot-instrumentation-1.0-SNAPSHOT.jar"))
}
dependencies {
classpath("org.utbot:utbot-gradle:1.0-SNAPSHOT")
}
</pre>
</details>
}
```

- Apply the plugin:

__Groovy:__
```Groovy
apply plugin: 'org.utbot.gradle.plugin'
```
__Kotlin DSL:__
```Kotlin
apply(plugin = "org.utbot.gradle.plugin")
```

### How to configure the log level

Expand All @@ -252,6 +196,16 @@ Also note that the standard way to configure the log level (using the `log4j2.xm

[Read more about gradle log levels](https://docs.gradle.org/current/userguide/logging.html)

### Publishing

1. Read the [documentation](https://docs.gradle.org/current/userguide/publishing_gradle_plugins.html) about plugin publishing
2. Sign in to our [account](https://plugins.gradle.org/u/utbot) to get API keys (if you don't have a password, please contact [Nikita Stroganov](https://github.com/IdeaSeeker))
3. Run `utbot-gradle/plugin portal/publishPlugins` gradle task

You can check the published artifacts in the [remote repository](https://plugins.gradle.org/m2/org/utbot/utbot-gradle/).

Please note that the maximum archive size for publishing on the Gradle Plugin Portal is ~60Mb.

### Requirements

UTBot gradle plugin requires Gradle 6.8+