Clover-for-Grails Quick Start Guide

On this page:

Generating Clover Reports

Install the Clover-for-Grails plugin

Install the Clover-for-Grails plugin by running the following Grails command in the root of your Grails project directory.

grails install-plugin clover

Generating a basic Clover coverage report

To generate a basic Clover code coverage report, you need to add the Clover option -clover.on to the grails test-app command line target for running unit tests against your Grails project.

grails test-app -clover.on -clover.view

Passing the location of your clover.license file to the grails command line

If you have not placed your clover.license file within your Grails project or user home directory (as indicated in the Installation Guide), you can pass the license file's location to the grails command line by adding the Clover option -clover.license.path=/path/to/clover.license:

grails test-app -clover.on -clover.license.path=/path/to/clover.license

Configuring Clover-for-Grails

Clover-for-Grails supports the configuration options outlined in the code sample below. All of these configuration options are defined in a single clover {} code block, which itself is defined within the Groovy build configuration file (BuildConfig.groovy) of your Grails project.

clover {

 on = true|false // a boolean value indicating whether or not clover is enabled

 license.path = "/path/to/clover.license" // the location of the clover license file, if not in one of the default locations.

 debug = true|false // a boolean to toggle debugging on or off

 initstring = "" // the location to use for Clover to write out its database

 srcDirs = []  // an array of Strings of source directories to including in instrumentation

 includes = [] // an array of String Ant Glob Patterns to include for instrumentation

 excludes = [] // an array of String Ant Glob Patterns to exclude for instrumentation

 setuptask = {} // Gant script to be called instead of the default clover-setup

 reporttask = {} // Gant script to be called when tests have finished

}

Advanced Setup Configuration

Define a setuptask 'closure' in your clover {} code block to configure advanced options for your Groovy project's build processes. Here, you can define various attributes and elements of the clover-setup task.

The setuptask closure is passed the following parameters:

• ant — an instance of a org.codehaus.gant.GantBuilder
• binding — the groovy binding for accessing project variables
• plugin — the clover grails plugin that invoked this closure

The syntax used to define your clover-setup tasks in the clover {} code block is Gant.

 // Example setuptask closure that will be invoked to configure clover.
 // Any Clover initialisation tasks should be defined here.
 // All attributes on the ant clover-setup task, which are
 // supported by your source code, can be defined here.

 setuptask = { ant, binding, plugin ->

    ant.'clover-setup'(initstring: "${binding.projectWorkDir}/clover/custom/clover.db") {
       fileset(dir: "grails-app") { includes: "**/*.groovy"}
    }

 }

Advanced Report Configuration

Define a reporttask 'closure' in your clover {} code block to configure advanced report generation options for your Groovy project's build process. Here, you can define various attributes and elements of the clover-report task. In fact, any Clover Ant tasks and their attributes and elements may be used in this closure.
You would not normally include clover-setup tasks in the reporttask closure because the latter is executed after the clover-setup tasks have executed.

Like the reporttask closure, the reporttask closure is passed the following parameters:

• ant — an instance of a org.codehaus.gant.GantBuilder
• binding — the groovy binding for accessing project variables
• plugin — the clover grails plugin that invoked this closure

The syntax used to define your clover-report tasks or any other valid Ant task in the clover {} code block is Gant.

The following example clover {} code block and reporttask definition in your BuildConfig.groovy file will:

• generate a Clover report in both PDF and HTML formats and
• place the results in the build/clover/report subdirectory of your Grails project directory.

clover {

  // reports.dir defines the location of your Clover report output
  // within your Grails project.

  reports.dir = "build/clover/report"

  // The reporttask closure is invoked after all tests have run.

  reporttask = { ant, binding, plugin ->

    ant.mkdir(dir: "${clover.reports.dir}")

    ant.'clover-report' {

      ant.current(outfile: "${clover.reports.dir}/clover.pdf", summary: true) {
        format(type: "pdf")
      }

      ant.current(outfile: "${clover.reports.dir}") {
        format(type: "html")
        ant.columns {
          lineCount()
          complexity()
          filteredElements(format:"bar")
          uncoveredElements(format: "raw")
          totalElements(format: "raw")
          totalPercentageCovered()
        }
      }

      ant.current(outfile: "${clover.reports.dir}/clover.xml") {
        format(type: "xml")
      }

      ant.current(outfile: "${clover.reports.dir}") {
        format(type: "json")
      }

   }

   plugin.launchReport(clover.reports.dir)

}

Troubleshooting

If you find that Clover-for-Grails runs out of memory, try increasing the Grails PermGen allocation by either setting the JAVA_OPTS environment variable:

export JAVA_OPTS="-XX:MaxPermSize=192m"

set JAVA_OPTS="-XX:MaxPermSize=192m"

Alternatively, you can define this variable in the startGrails (Linux/UNIX/Mac OS X) or startGrails.bat (Windows) script in the <Grails Home Directory>/bin directory.

RELATED TOPICS

Clover 3.0 Early Access Program
Clover-for-Grails Installation and Upgrade Guide