The JWare/AntX build-core(capture) package contains tasks that support the capture and examination of Ant logs and System output buffers from within an Ant build script. The ability to look at logged output is particularly helpful to test scripts.

The main script-facing tasks in this package are: CaptureLogsTask (<capturelogs>), CaptureStreamsTask (<captureoutput>), AssertLoggedTask (<assertlogged>), CopyLoggedTask (<copylogged>), ClearLoggedTask (<clearlogged>), and InterpretLoggedTask (<evaluatelogged>).

This package is broken into two types of classes: LogsRecorders (captures the logged information) and Logs Users (reads and manipulates captured information). All recorders use the CapturedLogs fixture administrator to install themselves as iteration-based LogsRecorders. All log users use the CapturedLogs administrator to retrieve the nearest typed logs recorder.

Capturing Task Output

CaptureLogsTask records everything sent to the Ant logs by all enclosed tasks— it does not record messages sent to either the System.out or System.err streams. You can direct CaptureLogsTask to differentiate between "important" messages (usually sent with priority of WARNING or worse) and everything else. The CaptureStreamsTask on the other hand will capture any information written to either or both the System.out or System.err streams.

Examining and/or Saving Captured Output

AssertLoggedTask applies certain assertions to captured logs. Captured logs can be checked to see if a string exists, if a string does not exist, if a string exists a specific number of times (occurances), or if a set of strings exist in a specific order. A general regular expression match is also supported (the scope of expression is limited only by the regular expression engine used by your Ant runtime). AssertLoggedTask can be directed to look for its strings only in the "important" log set of its enclosing logs recorder. Actually, the AssertLoggedTask is a custom implementation of an InterpretLoggedTask which represents a task that can examine the logged information to see if the data passes some application-controlled criteria (as defined by a custom implementation of LogInterpreter).

CopyLoggedTask was added to allow test build scripts to support manual examination of test output or additional testing from within the JUnit test engine. As it turns out, copying logs is generally useful in build scripts for capturing warnings from other Ant tasks like javadoc, javac, etc. This means that <capturelogs> is not a "testing-only" task (unlike <assertlogged>).

Both CaptureLogsTasks and CaptureStreamsTasks can be nested; inner log recorders do not affect outer ones. By default, both <assertlogged> and <copylogged> apply to the nearest <capturelogs>. If a <captureoutput> has been installed instead of <capturelogs>, both <assertlogged> and <copylogged> can be directed to use this captured information using the common from="stdio" attribute setting (see examples below).

Example Usage:

  <capturelogs>
    <echo message="((Warning))"/>
    <assertlogged value="((Warning))" trueproperty="Was.warned"/>
    <assert issettrue="Was.warned"/>
    <echo level="verbose" message="((Verbose))"/>
    <assertlogged value="((Verbose))" occurances="0" msg="Broken importance check"/>
    <assertlogged important="no" value="((Verbose))" occurances="1"/>
    <assertlogged important="no">
       <string value="((Warning))"/>
       <string value="((Verbose))"/>
    </assertlogged>
   </capturelogs>

Nested logs recorders:

  <capturelogs>
    <echo message="((Warning.0))"/>
    <assertlogged value="((Warning.0))"/>
    <capturelogs importantFrom="warning">
      <assertlogged value="((Warning.0))" occurances="0"/>
      <echo level="info" message="((Info))"/>
      <assertlogged value="((Info)" occurances="0"/>
      <echo level="warning" message="((Warning.1))"/>
      <assertlogged value="((Warning.1))" reset="yes"/>
    </capturelogs>
    <assertlogged>
       <string value="((Warning.0))"/>
       <string value="((Info))"/>
       <string value="((Warning.1))"/>
    </assertlogged>
  </capturelogs>

Capturing System.err or System.out:

  <captureoutput from="stderr">
    <script .../>
    <copylogged from="stdio" tofile="${logs}/script.err/>
  </captureoutput>


[More Learning Materials]   [Documentation Problems]
( Updated: January 18 2005, 06:54 PM, -0400 )