Skip to content

Latest commit

 

History

History
248 lines (198 loc) · 7.6 KB

utbot-gradle.md

File metadata and controls

248 lines (198 loc) · 7.6 KB

Utbot gradle plugin

Utbot Gradle Plugin is a gradle plugin for generating tests and creating SARIF-reports.

The generateTestsAndSarifReport gradle task generates tests and SARIF-reports for all classes in your project (or only for classes specified in the configuration). In addition, it creates one big SARIF-report containing the results from all the processed files.

How to use

Please, check for the available versions here.

  • Apply the plugin:

    Groovy:

    plugins {
    id "org.utbot.gradle.plugin" version "..."
}

    Kotlin DSL:

    plugins {
    id("org.utbot.gradle.plugin") version "..."
}

  • Run gradle task utbot/generateTestsAndSarifReport to create a report.

How to configure

For example, the following configuration may be used:

Groovy:

sarifReport {
    targetClasses = ['com.abc.Main', 'com.qwerty.Util']
    projectRoot = 'C:/.../SomeDirectory'
    generatedTestsRelativeRoot = 'build/generated/test'
    sarifReportsRelativeRoot = 'build/generated/sarif'
    markGeneratedTestsDirectoryAsTestSourcesRoot = true
    testPrivateMethods = false
    projectType = 'purejvm'
    testFramework = 'junit5'
    mockFramework = 'mockito'
    generationTimeout = 60000L
    codegenLanguage = 'java'
    mockStrategy = 'other-packages'
    staticsMocking = 'mock-statics'
    forceStaticMocking = 'force'
    classesToMockAlways = ['org.slf4j.Logger', 'java.util.Random']
}

Kotlin DSL:

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)
    testPrivateMethods.set(false)
    projectType.set("purejvm")
    testFramework.set("junit5")
    mockFramework.set("mockito")
    generationTimeout.set(60000L)
    codegenLanguage.set("java")
    mockStrategy.set("other-packages")
    staticsMocking.set("mock-statics")
    forceStaticMocking.set("force")
    classesToMockAlways.set(listOf("org.slf4j.Logger", "java.util.Random"))
}

Also, you can configure the task using -P<parameterName>=<value> syntax.

For example,

generateTestsAndSarifReport
    -PtargetClasses='[com.abc.Main, com.qwerty.Util]'
    -PprojectRoot='C:/.../SomeDirectory'
    -PgeneratedTestsRelativeRoot='build/generated/test'
    -PsarifReportsRelativeRoot='build/generated/sarif'
    -PtestPrivateMethods='false'
    -PtestProjectType=purejvm
    -PtestFramework=junit5
    -PmockFramework=mockito
    -PgenerationTimeout=60000
    -PcodegenLanguage=java
    -PmockStrategy='other-packages'
    -PstaticsMocking='mock-statics'
    -PforceStaticMocking=force
    -PclassesToMockAlways='[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.

Description of fields:

  • targetClasses –

    • Classes for which the SARIF-report will be created. Uses all source classes from the user project if this list is empty.
    • By default, an empty list is used.

  • projectRoot –

    • Absolute path to the root of the relative paths in the SARIF-report.
    • By default, the root of your project is used.

  • generatedTestsRelativeRoot –

    • Relative path (against module root) to the root of the generated tests.
    • By default, 'build/generated/test' is used.

  • sarifReportsRelativeRoot –

    • Relative path (against module root) to the root of the SARIF reports.
    • By default, 'build/generated/sarif' is used.

  • markGeneratedTestsDirectoryAsTestSourcesRoot –

    • Mark the directory with generated tests as test sources root or not.
    • By default, true is used.

  • testPrivateMethods–

    • Generate tests for private methods or not.
    • By default, false is used.

  • projectType –

    • The type of project being analyzed.
    • Can be one of:
      • 'purejvm' (by default)
      • 'spring'
      • 'python'
      • 'javascript'

  • testFramework –

    • The name of the test framework to be used.
    • Can be one of:
      • 'junit4'
      • 'junit5' (by default)
      • 'testng'

  • mockFramework –

    • The name of the mock framework to be used.
    • Can be one of:
      • 'mockito' (by default)

  • generationTimeout –

    • Time budget for generating tests for one class (in milliseconds).
    • By default, 60 seconds is used.

  • codegenLanguage –

    • The language of the generated tests.
    • Can be one of:
      • 'java' (by default)
      • 'kotlin'

  • mockStrategy –

    • The mock strategy to be used.
    • Can be one of:
      • 'no-mocks' – do not use mock frameworks at all
      • 'other-packages' – mock all classes outside the current package except system ones (by default)
      • 'other-classes' – mock all classes outside the class under test except system ones

  • staticsMocking –

    • Use static methods mocking or not.
    • Can be one of:
      • 'do-not-mock-statics'
      • 'mock-statics' (by default)

  • forceStaticMocking –

    • Forces mocking static methods and constructors for classesToMockAlways classes or not.
    • Can be one of:
      • 'force' (by default)
      • 'do-not-force'
    • Note: We force static mocking independently on this setting for some classes (e.g. java.util.Random).

  • classesToMockAlways –

    • Classes to force mocking theirs static methods and constructors.
    • By default, some internal classes are used.

How to test

If you want to change the source code of the plugin or even the whole utbot-project, you need to do the following:

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

  • Add to your build file:

    Groovy:

    buildscript {
    repositories {
        mavenLocal()
    }
    dependencies {
        classpath "org.utbot:utbot-gradle:1.0-SNAPSHOT"
    }
}

    Kotlin DSL:

    buildscript {
    repositories {
        mavenLocal()
    }
    dependencies {
        classpath("org.utbot:utbot-gradle:1.0-SNAPSHOT")
    }
}

  • Apply the plugin:

    Groovy:

    apply plugin: 'org.utbot.gradle.plugin'

    Kotlin DSL:

    apply(plugin = "org.utbot.gradle.plugin")

How to configure the log level

To change the log level run the generateTestsAndSarifReport task with the appropriate flag.

For example, generateTestsAndSarifReport --debug

Note that the internal gradle log information will also be shown.

Also note that the standard way to configure the log level (using the log4j2.xml) does not work from gradle.

Read more about gradle log levels

Publishing

  1. Read the documentation about plugin publishing
  2. Sign in to our account to get API keys (if you don't have a password, please contact Nikita Stroganov)
  3. Run utbot-gradle/plugin portal/publishPlugins gradle task

You can check the published artifacts in the remote repository.

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

Requirements

UTBot gradle plugin requires Gradle 7.4.2+