You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by di...@apache.org on 2002/03/29 16:50:48 UTC
cvs commit: jakarta-commons/latka/xdocs xml-reference.xml users-guide.xml status.xml release-plan-1.0.xml proposal.xml mailing-lists.xml index.xml developers-guide.xml
dion 02/03/29 07:50:48
Added: latka/xdocs xml-reference.xml users-guide.xml status.xml
release-plan-1.0.xml proposal.xml mailing-lists.xml
index.xml developers-guide.xml
Log:
Generated files from docbook source (see /doc directory)
Keeping duplicates for maven testing
Revision Changes Path
1.1 jakarta-commons/latka/xdocs/xml-reference.xml
Index: xml-reference.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: Morgan Delagrange
Version: $Id: xml-reference.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Latka XML Reference</title><author email="mdelagra@yahoo.com">Morgan Delagrange</author><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><section name="Latka XML Reference">
<!-- REFENTRY: byteLength -->
<a name="latka.ref.byteLength"/><subsection name="byteLength">
<p>
validates the length of an HTTP(S) response
</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT byteLength EMPTY>
<!ATTLIST byteLength min CDATA "0"
max CDATA #IMPLIED
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>min</code></td>
<td>NUMBER</td>
<td><code>0</code></td>
<td>
Minimum number of bytes required for a valid
response. Implied. Defaults to
<code>0</code>.
</td>
</tr>
<tr>
<td><code>max</code></td>
<td>NUMBER</td>
<td><em>none</em></td>
<td>
Maximum number of bytes required for a valid
response. Optional. When absent, there is no
upper limit on the number of bytes in a valid
response.
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this validation, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.validate">validate</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A <code>byteLength</code> validation
passes if the HTTP(S) response is at least
<code>min</code>
bytes long, and (when specified) at most
<code>max</code> bytes long.
</p>
</p>
</subsection>
<!-- REFENTRY: COOKIE -->
<a name="latka.ref.cookie"/><subsection name="cookie">
<p>
validates the presence of an HTTP(S) cookie in a response
</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT cookie EMPTY>
<!ATTLIST cookie name CDATA #REQUIRED
value CDATA #IMPLIED
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>name</code></td>
<td>CDATA</td>
<td><em>none, but required</em></td>
<td>
The name of the cookie to look for.
Required.
</td>
</tr>
<tr>
<td><code>value</code></td>
<td>CDATA</td>
<td><em>none, optional</em></td>
<td>
The value that the cookie with the specified name should
have (if any).
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this validation, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.validate">validate</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A <code>cookie</code> validation
passes if the HTTP(S) response contains a cookie with the
specified <code>name</code>.
If a <code>value</code> is provided,
the cookie must also have the specified value.
</p>
</p>
</subsection>
<!-- REFENTRY: CREDENTIALS -->
<a name="latka.ref.credentials"/><subsection name="credentials">
<p>
username/password credentials for Basic HTTP authentication.
</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT credentials EMPTY>
<!ATTLIST credentials userName CDATA #REQUIRED
password CDATA #REQUIRED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>userName</code></td>
<td>CDATA</td>
<td><em>none, required</em></td>
<td>User name. Required.</td>
</tr>
<tr>
<td><code>password</code></td>
<td>CDATA</td>
<td><em>none, required</em></td>
<td>Password. Required.</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.request">request</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
Contains credentials for HTTP Basic Authentication.
</p>
</p>
</subsection>
<!-- REFENTRY: maxRequestTime -->
<a name="latka.ref.maxRequestTime"/><subsection name="maxRequestTime">
<p>validates the response time for an HTTP(S) request</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT maxRequestTime EMPTY>
<!ATTLIST maxRequestTime millis CDATA "30000"
message CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>millis</code></td>
<td>NUMBER</td>
<td><code>30000</code></td>
<td>
Maximum amount of time, in milliseconds, in which
a response must be returned to be considered a
valid response. Implied. Defaults to
<code>30000</code> milliseconds,
or 30 seconds.
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this validation, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.validate">validate</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A <code>maxRequestTime</code> validation
passes if the HTTP(S) response is obtained in no more than
<code>millis</code> milliseconds.
</p>
</p>
</subsection>
<!-- REFENTRY: PARAM -->
<a name="latka.ref.param"/><subsection name="param">
<p>indicates a request parameter as part of an HTTP(S) request to be executed</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT request (<a href="#latka.ref.paramName">paramName</a>, <a href="#latka.ref.paramValue">paramValue</a>)></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<p>
<em>None.</em>
</p>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.request">request</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A parameter to be submitted as part of a <a href="#latka.ref.request">request</a>.
</p>
</p>
</subsection>
<!-- REFENTRY: paramName -->
<a name="latka.ref.paramName"/><subsection name="paramName">
<p>the name part of a name/value pair parameter</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT paramName (#PCDATA)></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<p>
<em>None.</em>
</p>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.param">param</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
The name part of <a href="#latka.ref.param">param</a>
to be submitted as part of a <a href="#latka.ref.request">request</a>.
</p>
</p>
</subsection>
<!-- REFENTRY: paramValue -->
<a name="latka.ref.paramValue"/><subsection name="paramValue">
<p>the value part of a name/value pair parameter</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT paramValue (#PCDATA)></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<p>
<em>None.</em>
</p>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.param">param</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
The value part of <a href="#latka.ref.param">param</a>
to be submitted as part of a <a href="#latka.ref.request">request</a>.
</p>
</p>
</subsection>
<!-- REFENTRY: REGEXP -->
<a name="latka.ref.regexp"/><subsection name="regexp">
<p>
validates the presence or absence of a regular expression within an HTTP(S) response
</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT regexp EMPTY>
<!ATTLIST regexp pattern CDATA #REQUIRED
cond (true | false) "true"
ignoreCase (true | false) "false"
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>pattern</code></td>
<td>CDATA</td>
<td><em>none, but required.</em></td>
<td>
The regular expression to look for.
</td>
</tr>
<tr>
<td><code>cond</code></td>
<td>
<em>Enumeration:</em>
<ul>
<li><code>true</code></li>
<li><code>false</code></li>
</ul>
</td>
<td><code>true</code></td>
<td>
When <code>true</code>,
the given <code>pattern</code>
must match within the response.
When <code>false</code>,
the given <code>pattern</code>
must not match within the response.
</td>
</tr>
<tr>
<td><code>ignoreCase</code></td>
<td>
<em>Enumeration:</em>
<ul>
<li><code>true</code></li>
<li><code>false</code></li>
</ul>
</td>
<td><code>false</code></td>
<td>
When <code>true</code>,
case is ignored within the
given <code>pattern</code>.
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this validation, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.validate">validate</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A <code>maxRequestTime</code> validation
passes if the HTTP(S) response is obtained in no more than
<code>millis</code> milliseconds.
</p>
</p>
</subsection>
<!-- REFENTRY: REQUEST -->
<a name="latka.ref.request"/><subsection name="request">
<p>indicates an HTTP(S) request to be executed</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT request (<a href="#latka.ref.credentials">credentials</a>?, <a href="#latka.ref.param">param</a>*, <a href="#latka.ref.validate">validate</a>?)>
<!ATTLIST request path CDATA #REQUIRED
method (post | get) "get"
host CDATA #IMPLIED
port CDATA #IMPLIED
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<p>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>path</code></td>
<td>CDATA</td>
<td><em>none, but required</em></td>
<td>Request path. Required.</td>
</tr>
<tr>
<td><code>method</code></td>
<td>
<em>enumeration:</em>
<ul>
<li><code>get</code></li>
<li><code>post</code></li>
</ul>
</td>
<td><code>get</code></td>
<td>HTTP method. Implied. Defaults to <code>get</code>.</td>
</tr>
<tr>
<td><code>host</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Host to submit request to.
Optional.
When absent, uses default from <a href="#latka.ref.suite">suite</a>.
</td>
</tr>
<tr>
<td><code>port</code></td>
<td>NUMBER</td>
<td><em>depends upon protocol</em></td>
<td>
Port to submit request to.
Optional.
When absent, uses default from <a href="#latka.ref.suite">suite</a>.
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this validation, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.suite">suite</a></li>
<li><a href="#latka.ref.session">session</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
An HTTP(S) request to be executed.
</p>
</p>
</subsection>
<!-- REFENTRY: SESSION -->
<a name="latka.ref.session"/><subsection name="session">
<p>wrapper for a sequence of <a href="#latka.ref.request">request</a>s associated with the same state (session)</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT session (<a href="#latka.ref.request">request</a>+)>
<!ATTLIST session sessionId CDATA #IMPLIED
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>sessionId</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Unique identifier for this <code>session</code>.
Sessions with the same <code>sessionId</code>
will share the same underlying state (e.g., cookies, etc.)
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this <code>session</code>, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.suite">suite</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A <code>session</code> is a collection of
<a href="#latka.ref.request">request</a>s
that share the same underlying state. For example,
a cookie that returned in the response to one
<a href="#latka.ref.request">request</a>
will be included in subsequent
<a href="#latka.ref.request">request</a>s.
</p>
</p>
</subsection>
<!-- REFENTRY: statusCode -->
<a name="latka.ref.statusCode"/><subsection name="statusCode">
<p>validates an HTTP response code</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT statusCode EMPTY>
<!ATTLIST statusCode code CDATA "200"
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>code</code></td>
<td>NUMBER</td>
<td><code>200</code></td>
<td>
Numeric HTTP response code to expect.
Implied. Defaults to
<code>200</code>.
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this validation, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.validate">validate</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A <code>statusCode</code> validation
passes if the HTTP(S) response code for the given request
matches the value specified by
<code>code</code>.
</p>
</p>
</subsection>
<!-- REFENTRY: SUITE -->
<a name="latka.ref.suite"/><subsection name="suite">
<p>root element for a suite of tests</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT suite ( (<a href="#latka.ref.session">session</a> | <a href="#latka.ref.request">request</a>)+ )>
<!ATTLIST suite defaultHost CDATA #IMPLIED
defaultPort CDATA #IMPLIED
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>defaultHost</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Default hostname for <a href="#latka.ref.request">request</a>s. Optional.
</td>
</tr>
<tr>
<td><code>defaultPort</code></td>
<td>NUMBER</td>
<td><em>none</em></td>
<td>
Default port for <a href="#latka.ref.request">request</a>s. Optional.
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
Label associated with this <code>suite</code>, which may
be used in programatically generated documentation
or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<p>
<em>None.</em>
</p>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A <code>suite</code> is a collection of
<a href="#latka.ref.request">request</a>s
and <a href="#latka.ref.session">session</a>s
to execute.
</p>
</p>
</subsection>
<!-- REFENTRY: VALIDATE -->
<a name="latka.ref.validate"/><subsection name="validate">
<p>
indicates the suite of validations to apply to the
current <a href="#latka.ref.request">request</a> (and its response)
</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT validate (<a href="#latka.ref.byteLength">byteLength</a> | <a href="#latka.ref.cookie">cookie</a> | <a href="#latka.ref.maxRequestTime">maxRequestTime</a> | <a href="#latka.ref.regexp">regexp</a> | <a href="#latka.ref.statusCode">statusCode</a> | <a href="#latka.ref.xpath">xpath</a> )+></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<p>
<em>None.</em>
</p>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.request">request</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
Contains the set of validations to apply to the
current <a href="#latka.ref.request">request</a>
(and its response).
</p>
</p>
</subsection>
<!-- REFENTRY: xpath -->
<a name="latka.ref.xpath"/><subsection name="xpath">
<p>
xpath - assuming the HTTP(s) response contains XML, checks if an
<a href="http://www.w3.org/TR/xpath">XPath</a> expression matches
</p>
<p><a name=""><strong>DTD</strong></a><br/>
<source><!ELEMENT xpath EMPTY>
<!ATTLIST xpath select CDATA #REQUIRED
cond (true | false) "true"
value CDATA #IMPLIED
label CDATA #IMPLIED></source>
</p>
<p><a name=""><strong>Attributes</strong></a><br/>
<table>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr>
<tr>
<td><code>select</code></td>
<td>CDATA</td>
<td><em>none</em></td>
<td>
An XPath expression, designed to match a node in the
XML body of the response.
</td>
</tr>
<tr>
<td><code>cond</code></td>
<td>
<em>Enumeration:</em>
<ul>
<li><code>true</code></li>
<li><code>false</code></li>
</ul>
</td>
<td>
<code>true</code>
</td>
<td>
When <code>true</code>, the given XPath expression must match within the
response. When <code>false</code>, the given XPath expression must not
match within the response.
</td>
</tr>
<tr>
<td><code>value</code></td>
<td>
CDATA
</td>
<td>
<em>none, optional</em>
</td>
<td>
The value that the matched node should have, if any.
</td>
</tr>
<tr>
<td><code>label</code></td>
<td>
CDATA
</td>
<td>
<em>none</em>
</td>
<td>
Label associated with this validation, which may be used
in programatically generated documentation or reports. Optional.
</td>
</tr>
</table>
</p>
<p><a name=""><strong>Parents</strong></a><br/>
<ul>
<li><a href="#latka.ref.validate">validate</a></li>
</ul>
</p>
<p><a name=""><strong>Description</strong></a><br/>
<p>
A xpath validation passes if the HTTP(S) response body contains XML,
and the specified XPath expression matches (or not, depending on cond)
</p>
</p>
</subsection>
</section></body></document>
1.1 jakarta-commons/latka/xdocs/users-guide.xml
Index: users-guide.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: dIon Gillard
Version: $Id: users-guide.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Latka User's Guide</title><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><a name="introduction"/><section name="What is Latka">
<p>Latka is a functional (end-to-end) testing tool. It is implemented
in Java, and uses an XML syntax to define a series of HTTP (or HTTPS)
requests and a set of <i>validations</i> used to verify
that the request was processed correctly.
</p>
<p><b>Note:</b>
Although Latka currently supports only HTTP and HTTPS
request/response validations, it may be expanded to perform other
sorts of functional testing as warranted.
</p>
<p>
A simple example of a Latka XML test suite is shown in our
<a href="TestCommonsWebsite.xml">sample Latka test suite</a>.
When processed, this example would verify that the Jakarta Commons
homepage is present and that all the Commons Components have online
documenation.
</p>
</section><a name="run-latka"/><section name="Running Latka">
<p>A Latka test suite can be run:
<ul>
<li><p>From a command prompt</p></li>
<li><p>From the Latka web application</p></li>
<li><p>From a JUnit TestRunner</p></li>
</ul>
<p><b>Note:</b>To run Latka as an ant task, we suggest you use the JUnit
support of ant and write a small test case to invoke Latka, as discussed later</p>
</p>
<a name="run-latka-cmd"/><subsection name="Running Latka from the command prompt">
<p>There are two scripts (or batch files) shipped with latka:
<ol>
<li><p>latka.bat - for Windows machines</p></li>
<li><p>latka.sh - for Unix machines</p></li>
</ol>
</p>
<p>Both of the scripts take the following parameters: </p>
<ol>
<li>
<p>a test suite URL, e.g.
<source>file:./TestCommonsWebsite.xml</source> or
<source>http://jakarta.apache.org/commons/latka/TestCommonsWebsite.xml</source>
</p>
</li>
<li>
<p>Optionally properties files of Latka options
can be specified using the propfile parameter: <source>propfile:<file name></source>
</p></li>
<li>
<p>Optionally individual Latka options may be specified
using the prop parameter: <source>prop:<prop name>=<prop value></source>
</p>
</li>
</ol>
<p>For more information about what properties you can pass to
Latka, please see the <link linkend="properties">Latka Properties</link>
definition</p>
</subsection>
<a name="run-latka-webapp"/><subsection name="Running Latka from a web application (Under Construction)">
<p>The Latka release distribution comes with a web application
(latka-webapp.war) ready to deploy on a conforming Servlet 2.2/ JSP 1.1
container.</p>
<p>For example, to install the Latka web application into a
<a href="http://jakarta.apache.org/tomcat/">Tomcat 4</a> server, simply
copy the .war file to Tomcat's webapp directory, e.g.</p>
<source>[Win32] copy latka-webapp.war c:\tomcat4\webapps</source>
<p>or</p>
<source>[Unix] cp latka-webapp.war /usr/java/jtomcat4/webapps</source>
<p>and restart Tomcat</p>
<a name="using-latka-webapp"/><p><a name=""><strong>Using the Latka Web App</strong></a><br/>
<p>Once you've gotten the Latka web app running, it's
straightforward to use. You can either
<ol>
<li><p>Run a latka</p></li>
</ol>
</p>
</p>
</subsection>
<a name="run-latka-junit"/><subsection name="Running Latka as a JUnit Test Case">
<p>Here's hoping you're familiar with <i>JUnit</i></p>
<p>Latka ships with a class <a href="http://jakarta.apache.org/commons/latka/api/org/apache/commons/latka/junit/JUnitTestAdapter.html">JUnitTestAdapter</a>
that bridges Latka and JUnit. You can use this class to create JUnit
<i>Test</i>s from Latka's XML documents. For example, calling
<source>JUnitTestAdapter.createTestFromFile(fileName)</source>
with a valid Latka XML document's file name will return you back a JUnit Test,
ready to be added to a TestCase.</p>
<p>So, essentially you code a JUnit TestCase, and in the
<em>suite</em> method, you add the Tests created by JUnitTestAdapter
to the JUnit TestSuite.
<source>
public static Test suite() {
TestSuite suite = new TestSuite();
String fileName = "tests/samples/TestCommonsWebsite.xml";
suite.addTest(JUnitTestAdapter.createTestFromFile(fileName));
return suite;
}
</source>
</p>
<p>Once you have Latka's suite as a JUnit TestSuite, you can run it
using any JUnit TestRunner to execute the suite, including those shipped with
<a href="http://jakarta.apache.org/ant/">ant</a>.</p>
</subsection>
</section><a name="test-suite"/><section name="Anatomy of a test suite (Under Construction)">
<p>For a <em>reference</em> of the XML tags that can
possibly be used in developing latka test suites, see
<a href="http://jakarta.apache.org/commons/latka/xml-reference.html">The
XML Reference</a></p>
<p>A Latka test suite is an XML document with a top level element
of <i>suite</i></p>
</section><a name="properties"/><section name="Latka Properties (Under Construction)">
<p>Definitive list of properties and their meanings...</p>
</section></body></document>
1.1 jakarta-commons/latka/xdocs/status.xml
Index: status.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: Morgan Delagrange
Author: Doug Sale
Author: Rodney Waldhoff
Author: dIon Gillard
Version: $Id: status.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Status File for Jakarta Commons "Latka" Application</title><author email="mdelagra@yahoo.com">Morgan Delagrange</author><author email="dsale@us.britannica.com">Doug Sale</author><author email="rwaldhof@us.britannica.com">Rodney Waldhoff</author><author email="trongus@yahoo.com">dIon Gillard</author><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><section name="INTRODUCTION">
<p>Testing websites is a pain. Many regression tests for a website can
be verified automatically, speeding up the quality assurance process
and allowing the engineers to focus on the more important issues.
Additionally developers may want to monitor their development, QA
and production environment, so that they can be sure that everything
is running as they expect.</p>
<p>Latka is an HTTP functional testing suite for automated QA, acceptance and
regression testing. Latka suites are XML documents, which
can be written and/or modified without writing Java code. Latka tests can be
created quickly and modified easily, even by engineers without Java experience.</p>
</section><section name="2. DEPENDENCIES">
<p><em>Latka</em> relies on:</p>
<ul>
<li><p>Java Development Kit (Version 1.3 or later)</p></li>
<li><p>A JAXP 1.1 implementation</p></li>
<li><p>A SAX 2.0 parser conforming to the JAXP 1.1 APIs</p></li>
<li><p>An XSLT parser conforming to JAXP 1.1</p></li>
<li><p>HttpClient from Commons - for HTTP communcation</p></li>
<li><p>Jakarta Log4J logging package</p></li>
<li><p>JUnit - for testing</p></li>
<li><p>JSSE - SSL support (optional at runtime)</p></li>
<li><p>Jakarta-Regexp - regular expression tests and XML preprocessing (for variable support)</p></li>
<li><p>JDOM - for building XML reports</p></li>
</ul>
</section><section name="3. RELEASE INFO">
<p>Current Release: <a href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-latka/1.0/">
1.0 alpha 1</a></p>
<p>Planned Next Release: 1.0, timeframe: None defined</p>
</section><section name="4. COMMITTERS">
<p>The following individuals are the primary developers and
maintainers of this component. Developers who plan to use
<em>Latka</em> in their own projects are encouraged to collaborate
on the future development of this component to ensure that it continues to meet
a variety of needs.</p>
<ul>
<li><p>Morgan Delagrange</p></li>
<li><p>Doug Sale</p></li>
<li><p>Rodney Waldhoff</p></li>
<li><p>Jeff Turner (part-time)</p></li>
<li><p>dIon Gillard</p></li>
</ul>
</section><section name="5. DEVELOPMENT STATUS">
<p>Latka development status:</p>
<ul>
<li><p>Latka 1.0 Alpha 1 released</p></li>
<li><p>Latka library and command line interface:</p>
<p> Fully functional, but with potential interface changes
forthcoming.</p></li>
<li><p>Latka tag library (in Jakarta Taglibs):</p>
<p> Experimental, unstable.</p></li>
<li><p>Latka web application (in Commons Sandbox):</p>
<p> Experimental, promising but unstable.</p></li>
</ul>
<subsection name="Todo items:">
<ul>
<li><p>Add a universal mechanism for negating
validators. Currently regexp and xpath validators implement negation internally
as a special <literal moreinfo="none">cond</literal> attribute. This adds somewhat to the
internal complexity. It would be better to have the framework handle negation by
being able to wrap tests in a <not/> element.</p></li>
<li><p>Make the inclusion of individual validators
optional at build time.</p></li>
<li><p>Set up Latka to use the proxy support of later
<a href="http://jakarta.apache.org/commons/httpclient/">HttpClient</a>
builds</p></li>
<li><p>Write unit tests for each validator, with a mock
object implementing the Response interface</p></li>
<li><p>Fix the webpages build so that it builds into
the build/docs directory and then copies to commons</p></li>
<li><p>Create better documentation, especially the
<a href="users-guide.html">User's Guide</a> and
<a href="developers-guide.html">Developer's Guide</a></p></li>
<li><p>Ensure coding standards are consistent across
the project's codebase, preferably using a tool such as
<a href="http://checkstyle.sourceforge.net/">CheckStyle</a></p>
</li>
<li><p>Add XMLValidate tasks to the build file so that
any XML doc with a DTD is checked before used</p></li>
</ul>
</subsection>
</section></body></document>
1.1 jakarta-commons/latka/xdocs/release-plan-1.0.xml
Index: release-plan-1.0.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: dIon Gillard
Version: $Id: release-plan-1.0.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Release Plan for Latka 1.0</title><author email="dion@apache.org">dIon Gillard</author><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><section name="Administrivia">
<p>This document describes a plan for a 1.0 release of the
Jakarta-Commons Latka component (for the remainder of this document, simply
"Latka").</p>
<p>As per the
<a href="http://jakarta.apache.org/site/decisions.html">
Jakarta/ASF guidelines</a>, this document doesn't mean anything until
accepted by the relevant committer community via a lazy majority vote
(hereafter, simply "lazy majority"). Once accepted, it may be replaced by an
alternative plan, again subject to lazy majority approval.</p>
<p>Non-binding votes (votes cast by those outside the relevant
committer community) are welcome, but only binding votes are significant for
decision making purposes.</p>
</section><section name="Objective">
<p>The objective of the 1.0 release of Latka is to provide a stable
and robust release focused on design clarity, forward compatibility, and ease
of use (i.e., with the intention of providing a stable foundation for the
further evolution of the Latka component).</p>
<p>Specifically, the 1.0 release seeks to
introduce and evaluate changes based upon the following
(ordered) criteria:
<ul>
<li><p>Freedom from defects (deviation from the
documented or reasonably expected behavior)</p></li>
<li><p>Interface and design consistency and clarity,
ease-of-use, and ease-of-extension.</p></li>
<li><p>Forward compatibility. That is, the ability to
add support for features that can be reasonably predicted without "breaking"
the external (and to a lesser degree, internal) interface of the component
</p></li>
</ul>
</p>
<p>The 1.0 release should also include:
<ul>
<li><p>Adequate documentation (including both
API-level/JavaDoc documentation as well documentation suitable for use on the
Jakarta-Commons site)</p></li>
<li><p>A substantial unit and functional test suite
suitable for ensuring the quality and compatibility of release 1.0 and
subsequent releases.</p></li>
<li><p>A clear demarcation of the "internal" and
"external" interfaces within Latka, as defined in the
<a href="http://jakarta.apache.org/commons/versioning.html">
Versioning Guidelines</a> document</p></li>
</ul>
</p>
</section><section name="Release Manager">
<p><a href="mailto:dion@apache.org">dIon Gillard</a>
(assuming no one else is really itching to do it)</p>
</section><section name="Timeline">
<p>(All days ending at 23:59:59 GMT in case of dispute.)
<ul>
<li>
<p>Review Period</p>
<p>Friday, March 29 - Friday, 5 April 2002</p>
<p>During the Review Period specific design, functional and
contract changes to Latka will be considered on the Jakarta-Commons mailing
list, using the following process:
<ul>
<li><p>Any developer or committer that
would like to see a specific change (or group of changes) enacted or
rolled back will suggest it on the <a href="jakarta-commons@jakarta.apache.org">
Jakarta-Commons mailing list</a></p></li>
<li><p>Any interested committer that
opposes a given change (or group of changes) is obligated to indicate this
disapproval on the list during the Review Period.</p></li>
<li><p>We will seek, but not strictly
require consensus on each decision point. If consensus cannot be reached,
any committer may call for a vote to resolve the issue via a lazy majority vote.
</p></li>
</ul>
</p>
<p>The Review Period may be closed before 5 April 2002,
given one "workday"'s notice and lazy majority approval.</p>
<p>The Review Period may be extended by one week (at a
time) given lazy majority approval, in case issues still need to be resolved.
</p>
</li>
<li>
<p>Implementation Period</p>
<p>Friday, 5 April 2002 - Friday, 12 April 2002
(assuming the Review Period is not extended)</p>
<p>During this period, any remaining implementation,
testing and documentation will be completed. No new features or "public"
interface changes will be considered in-scope at this time (short of a
lazy-majority approved revised release plan or any "showstopper" defects).
</p>
<p>At the end of the Implementation Period, a formal
release vote will be called, subject to lazy approval.</p>
<p>A formal release vote may be called before 12 April,
but after the end of the Review Period, if appropriate.</p>
</li>
</ul>
</p>
</section></body></document>
1.1 jakarta-commons/latka/xdocs/proposal.xml
Index: proposal.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: Morgan Delagrange
Author: Doug Sale
Author: Rodney Waldhoff
Version: $Id: proposal.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Proposal for Latka Package</title><author email="mdelagra@yahoo.com">Morgan Delagrange</author><author email="dsale@us.britannica.com">Doug Sale</author><author email="rwaldhof@us.britannica.com">Rodney Waldhoff</author><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><section name="(0) Rationale">
<p>Testing websites is a pain. Many regression tests for a website can
be verified automatically, speeding up the quality assurance process and
allowing the engineers to focus on the more important issues. Additionally
developers may want to monitor their development, QA and production environment,
so that they can be sure that everything is running as they expect.</p>
<p>Latka is an HTTP functional testing suite for automated QA. Latka
suites are XML documents, which can be written and/or modified without writing
Java code. Latka tests can be created quickly and modified easily, even by
engineers without Java experience.</p>
</section><section name="(1) Scope of the Package">
<p>The <em>Latka</em> project shall develop an
XML-based syntax for HTTP-based functional tests. Latka will support, at the
least, SSL communication and cookies.</p>
<p>Included within Latka are classes that simulate a user agent.
While the backend HTTP communication is handled by the HttpClient Commons
component, the Latka interfaces simulate some of the behaviour of an actual web
browser, including automatically passing cookies from request to request in a
session. We hope to integrate these classes into a "useragent" package in
HttpClient at some point, since they are a useful abstraction and not tied to
Latka in any way, nor do they modify the core HttpClient classes.</p>
<p>Latka also includes several validations that can be performed
on the HTTP responses, including checking the status code, byte length, or
request timing. In addition you will be able to customize Latka with your own
validators by writing a couple of simple classes.</p>
</section><section name="(1.5) Interaction With Other Packages">
<p><em>Latka</em> relies on:</p>
<ul>
<li><p>Java Development Kit (Version 1.3 or later)</p></li>
<li><p>A JAXP 1.1 implementation</p></li>
<li><p>A SAX 2.0 parser conforming to the JAXP 1.1 APIs</p></li>
<li><p>An XSLT parser conforming to JAXP 1.1</p></li>
<li><p>HttpClient from Commons - for HTTP communcation</p></li>
<li><p>Logging component from Commons (not yet implemented)</p></li>
<li><p>JUnit - for testing</p></li>
<li><p>JSSE - SSL support (optional at runtime)</p></li>
<li><p>Jakarta-Regexp - regular expression tests and XML preprocessing (for variable support)</p></li>
<li><p>JDOM - for building XML reports</p></li>
</ul>
</section><section name="(2) Initial Source of the Package">
<p>The initial source has been committed to the Sandbox, and includes
almost all of the functionality described above.</p>
</section><section name="(3) Required Jakarta-Commons Resources">
<ul>
<li>
<p>CVS Repository - New directory <em>latka
</em> in the <em>jakarta-commons</em> CVS repository.</p>
</li>
<li><p>Mailing List - Discussions will take place on
the general <em>jakarta-commons@jakarta.apache.org</em> mailing
list. To help list subscribers identify messages of interest, it is suggested
that the message subject of messages about this component be prefixed with
[Latka].</p></li>
<li><p>Bugzilla - New component "Latka" under the
"Commons" product category, with appropriate version identifiers as needed.
</p></li>
<li><p>Jyve FAQ - New category "commons-latka" (when
available).</p></li>
</ul>
</section><section name="(4) Initial Committers">
<p>The initial committers on the Latka component shall be:</p>
<ul>
<li><p>Morgan Delagrange</p></li>
<li><p>Doug Sale</p></li>
<li><p>Rodney Waldhoff</p></li>
<li><p>TBD</p></li>
</ul>
</section></body></document>
1.1 jakarta-commons/latka/xdocs/mailing-lists.xml
Index: mailing-lists.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: dIon Gillard
Version: $Id: mailing-lists.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Mailing Lists for Latka</title><author email="dion@apache.org">dIon Gillard</author><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><section name="Lists">
<p>Latka is a currently a project under the
<a href="http://jakarta.apache.org/commons/">Jakarta Commons</a> banner.
As such, it uses the Commons mailing lists for development and user questions.
</p>
<p>You can
<ul>
<li><p>
<a href="mailto:commons-dev-subscribe@jakarta.apache.org">Subscribe</a>
to the list</p></li>
<li><p>
<a href="mailto:commons-dev-unsubscribe@jakarta.apache.org">Unsubscribe</a>
from the list, or</p></li>
<li><p>
<a href="http://www.mail-archive.com/commons-dev@jakarta.apache.org/">
Browse the archives</a></p></li>
</ul>
</p>
<p>To help make posts about Latka stand out more on the commons-dev
list, please prefix the subject of your post with [Latka]</p>
</section></body></document>
1.1 jakarta-commons/latka/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: Morgan Delagrange
Version: $Id: index.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Latka (Version 1.0 Alpha 2)</title><author email="mdelagra@yahoo.com">Morgan Delagrange</author><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><section name="Other Documentation">
<p>See the <a href="xml-reference.html">XML Reference</a>,
<a href="users-guide.html">User's Guide</a> and
<a href="api/index.html">API Docs</a> for more detailed information.
</p>
</section><section name="What is Latka?">
<p>
<i>Latka</i> is a functional (end-to-end) testing
tool. It is implemented in Java, and uses an XML syntax to define
a series of HTTP (or HTTPS) requests and a set of
<i>validations</i> used to verify that the request
was processed correctly.
</p>
<p><b>Note:</b>
Although Latka currently supports only HTTP and HTTPS
request/response validations, it may be expanded to perform other
sorts of functional testing as warranted.
</p>
<p>
A simple example of a Latka XML test suite is shown in our
<a href="TestCommonsWebsite.xml">sample Latka test suite</a>.
When processed, this example would verify that the Jakarta Commons
homepage is present and that all the Commons Components have online documenation.
</p>
</section><section name="Installing Latka">
<subsection name="Requirements">
<ul>
<li><p>JDK 1.3 or better</p></li>
<li><p>
(for optional web application)
Tomcat 4.0 B7 or better - does not work in Tomcat 3.2, untested in
other containers</p>
</li>
<li><p>
(for optional SSL support)
<a href="http://java.sun.com/security/index.html">Sun JSSE library</a>
</p>
</li>
</ul>
</subsection>
<subsection name="General installation">
<ol>
<li><p>
Download and uncompress the
<a href="http://jakarta.apache.org/builds/jakarta-commons/release/commons-latka">Latka distribution</a>.
</p>
</li>
<li><p>
If you wish to perform Latka test over SSL,
you need to configure your JVM with the
<a href="http://java.sun.com/security/index.html">Sun JSSE library</a>.
</p>
</li>
</ol>
</subsection>
<subsection name="Optional web application installation ">
<ol>
<li><p>
Copy the "webapp/latka-webapp.war" file from the
distribution to the "webapp" directory of Tomcat.</p>
</li>
<li><p>
If you have already configured log4j for Tomcat,
you should remove log4j.jar from the /WEB-INF/lib
directory of the Latka webapp. </p>
</li>
</ol>
</subsection>
</section><section name="Using Latka">
<subsection name="Running the sample tests">
<p><b>Note:</b>Command-line interface</p>
<ol>
<li>
<p>Open a command prompt inside the "bin" directory of the
distribution.</p>
</li>
<li><p>
Run the Latka batch script on one of the sample XML test suites
(e.g. "latka file:../tests/samples/TestCommonsWebsite.xml ").
</p>
</li>
</ol>
<p><b>Note:</b>Web application</p>
<ol>
<li><p>
Go to the index page of the Latka web application.</p>
</li>
<li><p>Select "Run a test from the server"</p></li>
<li><p>
In the test directory dialog box, enter the directory:
<latka distrubution directory>/tests/samples
</p>
</li>
<li><p>
Click on one of the tests to execute it.</p>
</li>
</ol>
</subsection>
<subsection name="Creating your own tests">
<p>
(More to come...) Examine the Latka DTD in the conf directory
for a list of all available elements. See the samples for typical syntax.
</p>
</subsection>
<subsection name="Running tests">
<p><b>Note:</b>Command-line interface</p>
<ol>
<li><p>
Open a command prompt inside the "bin" directory of the distribution.
</p>
</li>
<li>
<p>
Run the Latka script with no arguments for information on usage.
</p>
</li>
</ol>
<p><b>Note:</b>Web application</p>
<ol>
<li>
<p>Go to the index page of the Latka web application.</p>
</li>
<li><p>Select "Run a test from the server"</p></li>
<li><p>
In the test directory dialog box, enter the directory where your tests are located.
</p>
</li>
<li><p>Click on one of the tests to execute it.</p></li>
</ol>
</subsection>
<subsection name="Creating your custom validations">
<p><b>Note:</b>(More to come...)</p>
</subsection>
</section></body></document>
1.1 jakarta-commons/latka/xdocs/developers-guide.xml
Index: developers-guide.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--This document generated by docbook2document.xsl--><!--
Author: dIon Gillard
Version: $Id: developers-guide.xml,v 1.1 2002/03/29 15:50:47 dion Exp $
--><document><properties><title>Latka Developers's Guide</title><author email="commons-dev@jakarta.apache.org">
Commons Documentation Team
</author></properties><body><a name="introduction"/><section name="Introduction">
<p>These are informal notes gathered as I've started working
on <a href="index.html">Latka</a>. Hopefully they will make sense to
those coming after me, and possibly clarify the current state for the existing
</p>
</section><a name="coding-style"/><section name="Coding Style">
<p>Latka has some unusual coding conventions, which we've hopefully
captured using a tool, <a href="http://checkstyle.sourceforge.net">CheckStyle
</a>.</p>
<p>Onto the conventions... The Sun coding conventions are followed in
most places, except for the items that follow</p>
<ul>
<li><p>private and protected member variables begin with an
underscore, <source>_requestSucceeded</source></p></li>
<li><p>private methods also begin with an underscore on
rare occasions (mainly when there is some public method and protected/private
method with an otherwise identical signature)</p>
</li>
<li><p>Javadoc on classes and methods is not yet complete.
Feel free to help out here :-)</p></li>
</ul>
</section><a name="general-practices"/><section name="General Practices">
<p>Here are some of the development practices of the Latka team</p>
<ul>
<li><p>Before committing any changes, run a cvs diff to
ensure unexpected changes are not being introduced</p>
</li>
<li><p>Before committing java source code changes, do a
clean build of the project to ensure all code still compiles. Run all testcases
to ensure the code isn't broken. Run the checkstyle task to ensure code meets
the project's current standards</p>
</li>
<li><p>Before committing changes to the web pages:
<ol>
<li><p>Ensure the original docbook is valid by
validating the XML against the docbook DTD</p>
</li>
<li><p>do a clean build of the webpages target in
the main build file and view the resulting output</p>
</li>
</ol>
</p>
</li>
</ul>
</section></body></document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>