Custom Reports with PurrPackage

This document is unfinished TODO.

First steps: Creating reports at build time

PurrPackage's reports use JavaScript and DHTML extensively, as is common these days. Sometimes, however, one needs plain text report, maybe just a simple one to include in an email. Or Facebook. PurrPackages supports this--you can write JavaScript that will be run at buildTime to generate the report.

To see how, look at the sample code base. First, notice in "ant-build.xml" or in the build.gradle file the reference to "buildTimeReports.js" this script is run just after PurrPackage has generated the rest of its reports.

Let's examine this script at a high level, particular the three points highlighted in its own documentation. (Open this is a new window FIXME.)

  1. The script can access all of the data that PurrPackage produces through the "buildTimeReportSupport" object. This main properties of this object are as follows:
    • coverageDataSupport: All of the coverage data with the policy applied.
    • policyText: The raw text of the coverage data that the script attempted to apply.
    • Some debugging support, in the form of boolean error indicators: coverageDataRead, coverageDataApplied, policyRead, and policyApplied, and the "errorDescription()" function which is a readable string based on these. When all is working, the booleans will all be true. However, if the policy file is missing, "policyRead" will be false, and if it is no valid JavaScript, "policyApplied" will be false.
  2. Next, we perform a typical iteration over coverage data. More details on this are supplied at all. Here, we are simply counting occurences of policy failures.
  3. JavaScript has no built-in I/O, so PurrPackage supplies some minimal support:
    • writeFile( relativePath, text ) which writes the text to the file relative to PurrPackage's output directory. (That value is stored in the baseDirUrl field.)
    • readFile( relativePath ) which reads a text file relative to your script's location. (That value is stored in the buildDirUrl field.)
    In fact, PurrPackage initializes an instance of the full featured Envjs headless browser before running your script. Envjs supports a wide range of operations; it is even possible to load and run javascript libraries such as Dojo, Prototype, or JQuery through Envjs, if you wish to do so.

Writing a custom browser based report

It is not much harder to produce a browser based report. The FIXME link to simpleCustom report is a stripped down report to illustrate how to get started writing your own report.

Modifying the default report.

Of course, feel free to make a copy of policyBrowser.html, and hack away at it. Just like the simple custom report above, it consists of static files. All the coverage data comes from the JSON files.

Most of the formatting in policyBrowser.html is done with TrimPath templates; if you just want to add a modify a column or two, you can just replace the template files in the simpleTemplates directory with ones you prefer. For example, if you prefer to ignore branch coverage and only count line coverage, just replace "elementCounts" with "lineCounts" in those template.

Next Steps

The JSON coverage data documentation explains all the data that is available to you from PurrPackage.