<?xml version="1.0"?>
<document>

  <properties>
    <title>Maven Latka Plug-in</title>
    <author email="dion@apache.org">dIon Gillard</author>
  </properties>

  <body>
    <section name="Contents">
      <p>The following sections are available in the Latka plugin documentation</p>
      <ol>
        <li><a href="#Overview">An overview of how this plugin works</a></li>
        <li><a href="#Customizing Latka">How to get more from Latka</a></li>
        <li><a href="#Generating Suites">How to generate Latka test suites</a></li>
        <li><a href="#Futures">What's in store for the Latka plugin</a></li>
      </ol>
    </section>
    <section name="Overview">
      <p>
        This plugin runs 
        <a href="http://jakarta.apache.org/commons/latka/index.html">Latka</a>
        web testing scripts.
      </p>
      <p>
        To use the plugin, you simply need to create some Latka test 
        scripts and place them in the <code>src/test/latka</code> directory.
      </p>
      <p>
        To execute the scripts, simply run
      </p>
      <source>maven latka</source>
      <p>
        By default this will simply print the results of running your
        Latka test suite to the console, and if the suite(s) failed,
        the build is stopped with an appropriate exception
      </p>
    </section>
    <section name="Customizing Latka">
      <p>
        Latka can be customised in many ways when running within
        the plugin. The Latka docs should be read thoroughly first as they
        should contain far more detail on the ways Latka can be tweaked.
      </p>
      <subsection name="XML Report">
        <p>
          Latka has the concept of <strong>listeners</strong>, classes
          whose job it is to listen for, and report on the progress of
          a Latka suite.
        </p>
        <p>
          Latka looks for a listener at the start of the suite tag as 
          a <a href="http://jakarta.apache.org/commons/jelly/">Jelly</a>
          variable named <code>latkaEventListener</code>. If one is not found,
          Latka notes this internally and creates an <code>XMLReporter</code>
          as the default listener.
        </p>
        <p>
          You can provide your own listener to Latka simply by using jelly's
          <code>new</code> tag <strong>before</strong> the suite tag, e.g.
        </p>
        <source><![CDATA[
<j:new var="latkaEventListener" className="org.apache.commons.latka.XMLReporter" />
]]></source>
        <p>
          Once the suite is complete, you can then access the XML report using
          all the usual jelly xml tags. For example, to simply print out the
          resulting report in XML format use the following:
        </p>
        <source><![CDATA[${latkaEventListener.documentAsString}]]></source>
        <p>
          Once you have the report, you can then do anything else you may like
          such as
          <ul>
            <li>Writing the report to a file using <code>j:file</code></li>
            <li>
              Perform JSL transformations on the report to generate
              documentation
            </li>
            <li>Extract pieces of the report using Jelly's XML tags</li>            
          </ul>
        </p>
      </subsection>
    </section>

    <section name="Generating Suites">
      <p>
        The plugin has a goal <strong>(latka:jmeter-convert)</strong>
        that takes a set of requests as recorded by 
        <a href="http://jakarta.apache.org/jmeter/index.html">JMeter</a>'s
        Http Proxy and converts them into a Latka suite. You can easily set up
        a browser with the correct proxy settings, and simply by using
        your web application, you can create tests that this plugin can
        later replay.
      </p>
      <p>
        The JMeter documentation contains a section on setting up the HTTP
        Proxy feature. This allows you to set 'listen' to requests being
        sent to the application and save the request details in XML format.
        JMeter can be set up to filter out requests by specifying a regular
        expression to match the incoming requests. This lets you only record
        relevant requests for your tests, e.g. HTML or JSP files, Struts
        actions with a .do extension etc.
      </p>
      <p>
        The <code>jmeter-convert</code> goal looks for a property passed to
        Maven, <code>jmeterFile</code>. If this file exists, the plugin
        blindly assumes it's a JMeter file and generates a corresponding
        Latka suite, containing all the requests in the JMeter file with
        the appropriate web server, port, request path and parameters.
      </p>
      <p>
        The file that is generated, 
        <code>${maven.build.dir}/latka/jmeter-suite.latka</code>, can then
        be editied and placed in the Latka source directory.
      </p>
      <p>
        To convert a file, say <code>C:\JMeter\test.jmx</code>, into a Latka
        suite, invoke Maven like this:
      </p>
      <source>maven -DjmeterFile=C:\JMeter\test.jmx latka:jmeter-convert</source>
      <p>
        This will produce a file, <code>target\latka\jmeter-suite.latka</code>
        ready for editing or execution.
      </p>
    </section>
    
    <section name="Futures">
      <ul>
        <li>
          The Latka Jelly tags are only new, and we're sure we'll find more bugs
          in them as time goes by, so first on the agenda is those pesky bugs and
          making Latka rock solid within Maven.
        </li>
        <li>
          Secondly a way to generate xdoc reports from the Latka XML Reporter,
          so that the Latka results can be incorporated into the site reports
        </li>
        <li>
          Exposing more detail about requests and responses to Jelly so
          people can get at them easily
        </li>
        <li>
          Your suggestions are always welcome!
        </li>
      </ul>
    </section>
 </body>
</document>
