Anteater User Manual

Anteater's default behaviour is fully configurable from the command-line or from Ant properties. For further information on how this is accomplished, check out the Configuration and Grouping sections.

For now, note that one can change the default host, port and debug level by defining the default.host, default.port and default.debug properties respectively, either by defining properties like this, just before your first task:

<group id="default">
  <property name="debug" value="1"/> <!-- 0 lowest, 10 highest -->
  <property name="host" value="mysite.com"/>
  <property name="port" value="8080"/>
</group>

You can also use the alternative <property name="default.debug" value="1"/> syntax, or from the command-line using the -Ddefault.debug=1 argument to the anteater script. Please refer to the Grouping section for details on what can be customized.

Anteater has a pluggable logging system. By default, a text logger logs to the screen. The other main logger is an XML logger. You can configure Anteater to use the XML logger as well by adding the following:

<group id="default">
  <logger type="xml"/>
  <logger type="colour"/>
</group>

Then if you look in the logs/ directory, you'll see some XML files, one per Anteater task. These XML files are in roughly the same format as those produced by Ant's <unit> task. This is so that we can reuse Ant's <junitreport> task to style them to HTML. Rather than getting your hands dirty with <unitreport>, you can invoke Anteater's pre-written reporting target with:

<target name="report" description="Generate a HTML report">
  <ant antfile="${anteater.report}">
    <property name="log.dir" value="${log.dir}"/>
    <property name="report.dir" value="reports"/>
  </ant>
</target>

The 'log.dir' property may be omitted, in which case it defaults to 'logs', the same default as the XML logger uses.

An example of what the output looks like can be found at http://aft.sourceforge.net/example_output/frames/. A non-frames version is also available.

Anteater tasks' behaviour is configured through properties of the group to which the task belongs. Currently recognised properties are host, port, debug, timeout, protocol, haltonerror, enable and usetidy. So if we had:

<group id="cocoontests">
  <property name="host" value="myhost.com"/>
  <property name="port" value="8080"/>
  <property name="debug" value="0"/>
</group>
<httpRequest group="cocoontests" ... />
<httpRequest group="cocoontests" ... />

Then those tasks would run against myhost.com:8080, with debug level 0, unless overridden by attributes on the httpRequest object. See the Configuration section for more details.

Group properties can also be set from outside a group:

<property name="cocoontests.debug" value="2"/>

This allows group values to be specified in properties files outside the test script, or from the command-line, eg:

anteater -Dcocoontests.host=localhost -Dcocoontests.debug=2 -f tests.xml

Since a Group object is an Anteater object, a Group can belong to another Group, either by nesting:

<group id="a">
  <property name="host" value="myhost.com"/>
  <group id="b"/>
</group>

or by the inherits attribute (group also works):

<group id="a">
  <property name="host" value="myhost.com"/>
</group>
<group id="b" inherits="a"/>

Group elements are inherited in what I hope seems a natural manner. Properties are passed through unless overridden, so b in the above example has host myhost.com. Loggers are passed through, unless any loggers are defined in the child group. Same with sessions.

There is an implicit default group, to which all tasks belong unless otherwise indicated. If the default group were written out, it would look like this:

<group id="default">
  <session/>
  <logger type="colour"/>
  <property name="host" value="localhost"/>
  <property name="debug" value="0"/>
  <property name="port" value="BUILTIN,8080"/>
  <property name="timeout" value="30s"/>
  <property name="protocol" value="HTTP/1.0"/>
  <property name="haltonerror" value="false"/>
  <property name="usetidy" value="false"/>
  <property name="usetidy-server" value="false"/>
  <property name="filename-format" value="true"/>
  <property name="overwrite" value="true"/>
  <property name="enable" value="true"/>

  <!-- Declare all other groups as children of 'default' here -->
  <group refid=".."/>
  ...
</group>

So by default, all tasks get a session, and a logger that prints to stdout, plus a bunch of properties used to configure the default Anteater behaviour.

The default group can be augmented and modified by the user, by declaring a group with id default. This way, we can override specific properties for all tasks:

<group id='default'>
  <property name="host" value="myhost.com"/>
  <property name="port" value="8080"/>
</group>

Or add another logger for all tasks:

<group id='default'>
    <logger type="xml"/>
</group>

All other items are inherited from the default defaults.

And of course the default group properties can be overridden at the command-line, e.g. -Ddefault.host=myotherhost.com or -Ddefault.debug=10.

The purpose of grouping has been to make simple things easier, and complicated things possible. Some scenarios, from simple to complex:

Simple grouping

Moderate grouping

<group id="default">
  <logger type="minimal"/>
  <logger type="xml" todir="${log.dir}"/>
</group>

Advanced grouping

<project name="groupdemo" default="main">
  <taskdef resource="META-INF/Anteater.tasks"/>
  <typedef resource="META-INF/Anteater.types"/>

  <group id="mytests">
    <property name="debug" value="0"/>
  </group>
  <group id="livesite" inherits="mytests">
    <property name="host" value="www.mysite.com"/>
    <logger type="xml" todir="{docs.dir}"/> <!--
    HTML report -->
  </group>
  <group id="devsite" inherits="mytests">
    <property name="host" value="www.mysite-dev.com"/>
    <property name="debug" value="1"/> <!-- devsite a bit unstable -->
    <property name="failonerror" value="true"/> <!-- Don't waste time testing whole site -->

    <group id="devsite-brokenbit"> <!-- Very broken bit of devsite -->
      <property name="debug" value="10"/> </group>
  </group>

  <target name="main">
    <!-- Will have debug=10, host=www.mysite-dev.com, failonerror=true, and log
    to the console -->
    <httpRequest group="devsite-brokenbit" path="/broken.html"/>
  </target>
</project>

Anteater extends Ant with a number of new tags: HTTP "action" tasks, "matcher" tasks for checking returned content, plus structural, configuration and metadata tags.

Action tasks

Matcher (validator) tasks

Structural, configuration and metadata objects

Each action task can contain one or more match tasks. An action task corresponds to a particular message you expect to receive from a Web service or client.

The match tasks associated with an action task describe the HTTP message you expect to receive. A match task is considered to be successful if all the associated matcher tests succeed. If one test fails, the match task that contains it is fails.

If multiple match tasks are specified for an action task, each match task is executed in turn, until one of them succeeds, at which point the matching process stops. If a match task succeeds, the action task that contains it succeeds. If none of the match tasks succeed, the action task is considered to fail, and it will be reported as such. In other words, if we had:

<httpRequest path="/foo.xml">
  <match>
    <A ../>
    <B ../>
  </match>
  <match>
    <C ../>
    <D ../>
    <E ../>
</match>

Then the httpRequest task would succeed if A and B succeeded, or if C, D and E all succeeded. In boolean logic, this is (A and B) or (C and D and E).

Anteater implements a 'shortcut boolean evaluation' policy. As soon as a <match> succeeds, the action task concludes. Likewise, as soon as a matcher test fails (eg <C ../>, none of the others (D, E) are processed.

If no match tasks are specified for an action task, the action task is considered successful as soon as it finishes. An action task that sends an HTTP request is considered finished as soon as the response is read from the Web server. An action task that listens for an incoming request is considered successful as soon as a request is received on the listening URL and the response is sent back to the client.

Let's consider the following simple example:

<target name="simple">
  <soapRequest
    description="Post a simple SOAP request">
    href="http://services.xmethods.net:80/soap"
    content="test/requests/get-quote">
    <namespace prefix="soap" uri="http://schemas.xmlsoap.org/soap/envelope/"/>
    <namespace prefix="n" uri="urn:xmethods-delayed-quotes"/>
    <match>
      <responseCode value="200"/>
      <xpath select="/soap:Envelope/soap:Body/n:getQuoteResponse/Result"/>
    </match>
  </soapRequest>
</target>

In this example we can identify the following Anteater tasks:

• soapRequest: the action task
• namespace: namespace declaration
• match: the match task
• responseCode and xpath: the test tasks

Examples

Send an HTTP GET request to http://localhost:8080/:

<httpRequest/>

Equivalent to an HTTP GET request to http://localhost/:

<httpRequest port="80"/>

Equivalent to an HTTP POST request to http://localhost:8080/servlets/example passing the content of /etc/passwd to the Web server:

<httpRequest path="/servlets/example" method="POST" content="/etc/passwd"/>

Examples

This example demonstrates how a listener's match tasks and testers can be arranged to implement if/then/else logic.

The incoming request can be a SOAP message containing either an receipt acknowledge message or a SOAP fault message, indicating an error.

<listener path="/receipt">
    <match method="POST">
      <xpath select="/soap:Envelope/soap:Body/receipt-ack"/>
      <xpath select="/soap:Envelope/soap:Body/response-to" assign="replyHref"/>
      <sendResponse href="${replyHref}/>
    </match>
    <match assign="failed">
      <matchBody select="/soap:Envelope/soap:Body/rfq"/>
      <matchMethod code="POST"/>
    </match>
</listener>

Examples

Reads a local file, resources/responses/text.txt, and checks that its contents (ignoring whitespace) is a certain value.

              <fileRequest path="resources/responses/text.txt"
                           description="tests a text file">
                <match>
                  <contentEquals ignoreSpaces="true">
                    Here is some freeform text saved with DOS linefeeds.
                  </contentEquals>
                </match>
            </fileRequest>

<target name="test">
  <soapRequest href="http://some.remote.server/"
               content="some/file"/>

  <listener port="8080" path="/receiptAck" timeout="7200">
    <namespace prefix="soap" uri="http://schemas.xmlsoap.org/soap/envelope/"/>
    <match>
      <method value="POST"/>
      <xpath select="/soap:Envelope/soap:Body/receipt-ack"/>
      <sendResponse href="responses/response.xml"
                    contentType="text/xml"/>
    </match>
  </listener>
</target>

Examples

This example demonstrates how a listener's match tasks and testers can be arranged to implement if/then/else logic.

The incoming request can be a SOAP message containing either an receipt acknowledge message or a SOAP fault message, indicating an error.

<listener path="/receipt">
    <match method="POST">
      <xpath select="/soap:Envelope/soap:Body/receipt-ack"/>
      <xpath select="/soap:Envelope/soap:Body/response-to" assign="replyHref"/>
      <sendResponse href="${replyHref}/>
    </match>
    <match assign="failed">
      <matchBody select="/soap:Envelope/soap:Body/rfq"/>
      <matchMethod code="POST"/>
    </match>
</listener>

As noted in the Anteater_tags section, match tasks can be used as a form of boolean logic. Each match block contains a set of AND'ed tests (they must all pass), and as any match block's success renders the action task successful, they are effectively OR'ed together. Thus the task:

<httpRequest path="/foo.xml">
  <match>
    <A ../>
    <B ../>
  </match>
  <match>
    <C ../>
    <D ../>
    <E ../>
</match>

implements the boolean logic (A and B) or (C and D and E).

This can be exploited in various interesting ways. Here is how a listener can deliver different responses based on the value of a parameter:

<listener path="/foo">
  <match assign="chose123">
    <method value="GET"/>
    <parameter name="a" value="123"/>
    <sendResponse href="test/responses/good.html" contentType="text/html"/>
  </match>
  <match assign="chose456">
    <method value="GET"/>
    <parameter name="a" value="456"/>
    <sendResponse href="test/responses/bad.html" contentType="text/html"/>
  </match>
</listener>

Here is a larger example of how one can determine the type of server being tested, by using the 'assign' attribute on matchers:

<httpRequest path="/">
  <match assign="servertype" value="gnu-apache">
    <header name="Server" value="Apache/1.3.24 (Unix) Debian GNU/Linux"/>
  </match>
  <match assign="servertype" value="generic-apache">
    <header name="Server" assign="apache-version" pattern="Apache/([\d.]+)"/>
  </match>
  <match assign="servertype" value="IIS6">
    <header name="Server" value="Microsoft-IIS/6.0"/>
  </match>
  <match assign="servertype" value="generic-IIS">
    <header name="Server" pattern="IIS"/>
  </match>
  <match assign="servertype" value="unknown">
  </match>
</httpRequest>
<echo>servertype is ${servertype}</echo>

The value a test task checks for can be assigned to an Ant property using the assign attribute. Such properties can be later referred to in Anteater and normal Ant tasks.

<soapRequest href="${url}"
             content="test/requests/get-quote">
  <match>
    <header name="Content-Length" assign="cl"/>
    <responseCode value="200" assign="rc"/>
    <xpath select="soap:Envelope/soap:Body/n:getQuoteResponse/Result"
           assign="result"/>
    <echo>XPath-selected the value '${result}'</echo>
  </match>
</soapRequest>

A major difference between Anteater and Ant is that properties can be assigned values multiple times, so you can reuse the same property across the test script. Properties assigned through the assign attribute can also be used immediately after their definition.

Elements allowed inside header: none

Examples

The following HTTP request sets the value of the Content-type header to text/html:

<httpRequest href="${url}">
  <header name="Content-type" value="text/html"/>
  <match>
    ...
  </match>
</httpRequest>

Test whether the Content-type header value returned by an HTTP request is set to text/html:

<httpRequest href="${url}">
  <match>
    <header name="Content-type" value="text/html"/>
  </match>
</httpRequest>

Assign the value of the Content-type header to an Anteater property:

<httpRequest href="${url}">
  <match>
    <header name="Content-type" assign="type"/>
    <echo>Content-type of the response is ${type}</echo>
  </match>
</httpRequest>

Test whether the Content-type header value received in an incoming HTTP request is any sort of text response, and store that type in a variable:

<httpRequest path="/good.html">
  <match assign="type" value="text">
    <header name="Content-Type" assign="texttype" pattern="text/(.*)"/>
  </match>
  <match assign="type" value="image">
    <header name="Content-Type" pattern="image/.*"/>
  </match>
</httpRequest>

Examples

Generates a POST request.

        <httpRequest path="/text.txt">
          <method>
            POST
          </method>
          <contentEquals>Posted contents</contentEquals>
          <match>
            ...
          </match>
      </httpRequest>

This example tests if the incoming request is a GET request:

<listener path="/abc">
  <match>
    <method value="GET"/>
    ...
  </match>
</listener>

Accept an incoming request, no matter what is the method, and assign the method type to the mth Anteater property:

<listener path="/abc">
  <match>
    <method assign="mth"/>
    <echo>Received a ${mth} request</echo>
  </match>
</listener>

Examples

Set a parameter in an outgoing HTTP request:

<httpRequest href="${url}">
  <parameter name="a" value="123"/>
  <match>
    ...
  </match>
</httpRequest>

Test if the a parameter is present in the request, and assign its value to the paramA Anteater property:

<listener path="/abc">
  <match>
    <parameter name="a" assign="paramA"/>
    ...
  </match>
</listener>

Return a different response based on a parameter value.

<listener path="/abc" description="wait for an incoming request">
      <match>
        <parameter name="a" value="123"/>
        <sendResponse href="resources/responses/good.html"
          contenttype="text/html"/>
      </match>

      <match>
        <parameter name="a" value="456"/>
        <sendResponse href="resources/responses/bad.html"
          contenttype="text/html"/>
      </match>
    </listener>

Elements allowed inside image: none

Examples

Here's a simple example of validating a gif image

        <httpRequest href="http://jakarta.apache.org/images/jakarta-logo.gif">
          <match>
            <image mimetype="image/gif"/>
          </match>
        </httpRequest>
        

Examples

The following example shows how to specify the value to be test against inline. It also ignores any whitespace differences between the two values.

              <httpRequest path="/text.txt"
                useTidy="false">
                <match>
                  <contentEquals ignoreSpaces="true">
                    Here is some freeform text saved with DOS linefeeds.
                  </contentEquals>
                </match>
            </httpRequest>

Here is how to generate a HTTP POST body dynamically with a Jelly script, and then require that the HTTP response body contain the text 'hello world':

               <httpRequest path="/text.txt">
                 <method>POST</method>
                 <contentEquals>
                   <jelly script="genBody.jelly"/>
                 </contentEquals>
                 <match>
                   <contentEquals ignoreSpaces="true">
                     hello world
                   </contentEquals>
                </match>
            </httpRequest>

Examples

This example checks if the page returned by the server is an HTML page:

<httpRequest useTidy="false" href="some URL">
  <match>
    <regexp><![CDATA[<html>.*</html>]]></regexp>
  </match>
</httpRequest>

Given a text file of the form:

...
struts-dev 795
struts-user 1740
taglibs-dev 342
taglibs-user 644
tomcat-dev 934
tomcat-user 2456
turbine-dev 263
turbine-jcs-dev 17
turbine-jcs-user 21
...

The following example extracts a single line from the file, and assigns part of it to a variable, ${tomcat-user}

<httpRequest
 href="http://jakarta.apache.org/~rubys/stats/subscribers/jakarta.apache.org">
  <match>
    <regexp assign="tomcat-user" singleLine="false" group="1">tomcat-user (.*)</regexp>
  </match>
</httpRequest>

Examples

The following example shows how to test the response code of an httpRequest task. The expected response code here is 200.

<httpRequest href="some URL">
  <match>
    <responseCode value="200"/>
  </match>
</httpRequest>

Here we use a regexp pattern to test if the response code was 300-class "Redirection" response.

<httpRequest href="some URL">
  <match>
    <responseCode pattern="3.."/>
  </match>
</httpRequest>

This is useful in conjunction with a property setter:

<httpRequest href="some URL">
  <match assign="ok">
    <responseCode pattern="2.."/>
  </match>
  <match assign="redirected">
    <responseCode pattern="3.."/>
  </match>
  <if>
    <isset property="redirected"/>
    <then>
      <echo>We were redirected... </echo>
    </then>
  </if>
</httpRequest>