Brockman

“A light, extensible build monitor.”

Links

Ant JUnit Freemarker

Table of Contents

5 minute Build Monitor - (build Brockman from source)

Preparations:

Steps:

  1. Download the latest source here.
  2. Run "ant" from the project root directory. This should build a out/dist/brockman.jar.
  3. Open brockman/buildstatus.html in a browser.
  4. Open a terminal on top of the browser (so you can see your results) and run 
    sh ./monitorbuild.sh
    or 
    monitorbuild.bat
  5. You should be watching Brockman build monitoring it's own build process.

Monitor your own build in 15 minutes

Preparations:

Steps:

  1. Download the latest binaries. If you decide to do this from source, make sure you don't overwrite your project's build.xml file with Brockman's build.xml
  2. Extract the zip file into your project directory. (There is a sample java project included in the testproject directory)
    3. Your directory structure should look something like this: 
            testproject/src/Calculator.java //my sample java file
        testproject/src/CalculatorTest.java //my sample test
        testproject/build.xml //my sample build.xml file
        testproject/monitorbuild.sh //brockman files...
        testproject/monitorbuild.bat
        testproject/brockman/config.xml
        testproject/brockman/brockman.jar
        testproject/brockman/buildstatus.css
        testproject/brockman/buildstatus.html
        testproject/brockman/buildstatus.js
        testproject/brockman/buildstatus.ftl
        testproject/brockman/prototype-1.4.0.ftl
  3. Note: Make sure your project has it's own build.xml, otherwise Brockman has nothing to monitor :)
  4. Open testproject/brockman/buildstatus.html in a browser.
  5. Open a terminal on top of the browser (so you can see your results) and run the testproject/monitorbuild.sh or testproject/monitorbuild.bat script.
  6. You should be watching Brockman monitoring your project

Alternatively

  1. Down the source and run "ant buildtestproject". This will build a template project complete with build monitor.
  2. Open testproject/brockman/buildstatus.html in a browser.
  3. Open a terminal on top of the browser (so you can see your results) and run testproject/monitorbuild.sh or testproject/monitorbuild.bat script.
  4. You should be watching Brockman monitoring your project

How to customise Brockman

A quick explanation of Brockman's Architecture

The core Brockman class is the SimpleMonitor. This class is an Ant Listener i.e. it listens to Ant events such as buildStarted, buildFinished, targetStarted, targetFinished and responds to them.

Every time the Brockman SimpleMonitor class is triggered by Ant, the tasks contained in config.xml are executed. The results of these tasks are formatted into the build status file buildstatus.xml which is then presented by the buildstatus.html and buildstatus.js web pages.

There are 4 customisable parts to Brockman:

  1. Build information gathering part - config.xml
  2. Build status format - buildstatus.ftl
  3. Presentation layer - buildstatus.html/.js
  4. Extending the Ant listener using Java

  1. Build information gathering part - config.xml

    Sample config.xml 
        <config>

    <taskdef id="junittestreader" classname="org.buildmonitor.brockman.tasks.junittestreader.JUnitReader" />

    <property id="files.buildstatus" value="brockman/buildstatus.xml"/>
    <property id="files.buildstatustemplate" value="brockman/buildstatus.ftl"/>

    <property id="htmlcolors.ok" value="green"/>
    <property id="htmlcolors.failed" value="red"/>
    <property id="htmlcolors.building" value="yellow"/>

    <property id="text.ok" value="OK"/>
    <property id="text.failed" value="Failed"/>
    <property id="text.building" value="Building"/>
    <property id="text.nocurrenttarget" value=""/>

    <junittestreader junitReportFilePath="TESTS-TestSuites.xml"/>

    </config>
    The config.xml file is split into 3 parts
    1. TaskDefs: These xml entries map Task ids to a Task class. They lightly correspond to Ant TaskDefs
    2. Properties: These are key value pairs - the kind that would normally be stored in a Java properties file. They can be overridden by passing 
      -Dyourproperty=yourvalue
      to Ant
    3. Tasks: These are the tasks that are run each time the build updates e.g. reading junit test reports, screen scraping, file counting etc. A task implements the Task interface.

    Existing Tasks

    • junittestreader - Supply this task with the location of the junit xml report file: 
                  <junittestreader junitReportFilePath="TESTS-TestSuites.xml"/>
      The task will populate a result object containing the number of tests, failures, errors, buildtime and timetaken. This is available for use in the freemarker template buildstatus.ftl e.g. 
                  <project>
            <total>${junittestreader[0].result.numTestCases}</total>
            <passing>${junittestreader[0].result.numPassing}</passing>
            <failures>${junittestreader[0].result.numFailures}</failures>
            <errors>${junittestreader[0].result.numErrors}</errors>
            <buildtime>${junittestreader[0].result.buildTime}</buildtime>
            <timetaken>${junittestreader[0].result.timeTaken}</timetaken>
            </project>
      Note, the tasks are indexed.
    • screenscraper - Supply this task with a url and regular expression information: 
                  <screenscraper url="http://www.buildmonitor.org"
            regex="(<h1>)(.*)(</h1>)"
            regexGroup="2"
            badUrlMessage="Can't find URL"
            badRegexMessage="Bad Regex"/>
      The task will scrape the web page for the supplied regular expression and populate a result object, available for use in the freemarker template buildstatus.ftl e.g. 
                  <websitetext>${screenscraper[0].result}</websitetext>
    • filecounter - Supply this task with a directory and a pattern it will count the files: 
                  <filecounter dir="." recurse="true" pattern="java" />
      The task will count the files and populate a result object, available for use in the freemarker template buildstatus.ftl e.g. 
                  <pendingtests>${filecounter[0].result}</pendingtests>
    • scp - Supply this task with a file, remote directory, and login information 
                  <scp hostname="myserver.com"
            username="myusername"
            password="mypassword"
            srcfile="brockman/buildstatus.xml"
            remotedirectory="/var/www/brockman/" />

      This is useful for publishing build monitor results on the web. You can do this by uploading the buildstatus.xml file in brockman to the directory on your webserver where you want the build monitor e.g. /var/www/brockman/.

      There are two different ways to log into a scp server. Password Authentication and Public Key Authentication. The scp task will attempt to use PublicKeyAuthentication if the keyfile attribute in the task is not blank. Otherwise it will use PublicKeyAuthentication.

      Uploading with SCP using PasswordAuthentication

      In order for this to work a username/password instead of public key authentication ssh server has to support PasswordAuthentication, on most linux servers this means making sure the line containing PasswordAuthentication = yes is in /etc/ssh/ssh_config

      Uploading with SCP using PublicKeyAuthentication

      Your server needs to be setup to support PublicKeyAuthentication. See http://www.uk-dave.com/tutorials/linux/sshkeys.php for instructions.

    • ftp - Supply this task with a file, destination file directory, and login information 
                  <ftp hostname="myserver.com"
            username="myusername"
            password="mypassword"
            srcfile="brockman/buildstatus.xml"
            destfile="/var/www/brockman/buildstatus.xml" />

      This is useful for publishing build monitor results on the web. You can do this by uploading the buildstatus.xml file in brockman to the directory on your webserver where you want the build monitor e.g. /var/www/brockman/.

    Custom Tasks

    To write your own custom task, implement the Task interface or extend the AbstractTask class. Then provide a mapping for the class in config.xml in the taskdef section.

  2. Buildstatus format

    This is a freemarker template. The default data model is populated with a buildstatus object and arrays of tasks. See above for explanations on how to use the tasks with freemarker.

  3. Presentation layer

    You can transform the buildstatus.xml file using Ajax, XSLT or your own preferred method.

  4. Extending the Ant Listener

    Override the extendDataModel method in the SimpleMonitor class and populate the freemarker data model hashmap with the data of your choice. This will then become available to the buildstatus.ftl freemarker template, allowing you to customise the buildstatus.xml file.

Integrating Brockman with CruiseControl

To integrate Brockman with Cruise Control,