Here be the user guide. Lets dive straight in...

<?xml version="1.0" encoding="ISO-8859-1" ?>

<eccles-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://eccles.sourceforget.net/eccles-config.xsd">
                  
    <test id="main">
          <log message="Hello World!!!"/>
          <run-test id="aChildTest"/>
    </test>

    <test id="aChildTest">
          <log message="Hello from the child test"/>
    </test>

</eccles-config>

Once Eccles has finished loading the input script, it will look for a top level test with the id of "main" to start execution. This test then outputs a message to the log before calling another top-level test (aChildTest)

It does not matter which order the tests are define in the file.

Eccles
Usage: eccles [-xlst filename] input_filename output_directory
    -xlst filename    | Process output file with the named stylesheet

The reason that you need to specify the output directory rather than the file is that potentionally more than one output file might be generated (i.e. copies of html pages or sub reports).

The generated report name is report.xml and if an xslt stylesheet is used to process the output, then the generated html file is report.html

Eccles has properties, like variables in a proper language. It is important to realise that these have their own scoping rules (again like proper languages). But first lets see a snippet of how we use them

<test id="main">
      <log message="Hello World!!!"/>
      <property define="aProperty" value="55"/>
      <log message="value is ${aProperty}"/>
      <property set="aProperty" value="hello"/>
      <log message="value is now ${aProperty}"/>
</test>

Ignore the syntax of the log tag, I'll deal with that in the next section.

As you can see, the property tag has two different meanings. If you use it with the define= property then you are bringing a new property into existance at the current level. It will exist for the rest of the lifetime of the parent tag.

When used with set=, the value for that property will be changed. The property does not have to be defined in the current scope, it can be wherever the property is in scope. And before you ask, that can be anywhere in the parent list of tags (or in a sibling tag after a property define)

When using the value= attribute, the property is assigned a string value. There are other attributes for other types you may need, which are intValue=, longValue=, doubleValue= and booleanValue=. See the property tag documentation for more information.

NOTE: Currently, only top level property names are supported in set=. This will be extended at some time to support sub-properties and indexing. (note this means you cannot use set="bean.property")

As you could see from the above, there is a specific way of accessing properties. Currently, Eccles using the expression evaluator from the Apache Beta-1 implentation of the JSTL (Java Standard Tag Library). This is exceedingly well featured and best of all saves me a lot of time implementing something else :-)

The general syntax is ${expression} where expression is some kind of Java-like expression. For more information on the supported EL syntax, check out The JSR-052 Expert Group.

One quick thing though, if you are trying to perform mathematical operations on properties then at least one of the properties must be a numeric type. Just using the property with the value= attribute will set that property to be a string. Look at using the typed attributes to get around this.

Yeah looping. This is a very basic tag for now, not at all like a for loop in a proper language, but rest assured there will be one at some point. For now you have the loop tag. The loop will always executed at least once. The being and end properties are not evluated. Here's an example:

<test id="main">
      <loop property="i" begin="0" end="10">
           <log message="Inside loop, i=${i}"/>
      </loop>
</test>

The else is optional. Example:

<if test="${foo>1}">
    <log message="the test was true"/>
    ....
</if><else>
    <log message="the test was false"/>
    ....
</else>

See also try tag, throw tag. Example:

<try>
    ....
    .... Some tags which might throw an exception
    ....
    <catch type="NullPointerException">
        <log message="caught a NPE. Exception details: ${exception}" />
        <log message="Caught in NullPointerException block. it was ${exception}" />
        <log message="Underlying exception was ${_exception}" />
        <log message="Underlying exception class was ${_exception.class}" />
    </catch>
    <catch type="Exception">
        <log message="caught another exception"/>
    </catch>
</try>	

There are many reporting levels, each of them having a type (for use in the script), a description and a level. Levels start at 1 (debug) and larger values increase the severity. Eventually we will support supression of errors from a certain level.

The default settings are:

Type	Description	Level
debug	Debug	1
info	Info	2
warn	Warning	3
error	Error	4
fatal	Fatal Error	5

Extra types can be added at the head of the xml file (before tests are listed) inside a config block (see the configuration block for more information). example:

<config>
    <add-report-type code="notfound" description="Server not found" level="3"/>
    <add-report-type code="pagesChecked" description="Pages Checked" level="0"/>
    <add-report-type code="carrot" description="Attack of a mutant carrot" level="15"/>
</config>

Using level=0 has a special meaning and is useful for counters. If this is used, then the report tag will never add these to the output file. However, the counters will still will be picked up by collate-reports and reported. This is useful for counting things that have worked, such as number of tests completed or number of pages processed.

The types are used with the report and asserttags. example:

<report type="error" message="some error has appeared">

If the type attribute is not set in the report tag, then it will default to "info"

The basic tag for actually checking whether things have worked or not is the assert tag. This tag will evaluate a test expression and if that works out to be false then send a message to the output file and (optionally) throw an exception.

If the test evaluates to true, then the tag can optionally be made to increment a counter.

Generating some sporadic results in the xml file is all well and good, but we really need some metrics. This is where the collate-results tag comes into its own.

The collate-results tag listens to all reports being generated by its children and keeps a count of these. When the tag goes out of scope it will write a count of these reports to the output file.

Better than that, it will pass on these errors to a result collater higher up in the call tree, with parent results being collated from all the children. This can allow you to get an overall picture of errors across the whole test, but also get lists of failures inside local tests as well.

The config block is a section for setting run wide options.The config block must appear before any test tags are used. A config block is not mandatory.