Latka (Version 1.0 Alpha 1)

## What is Latka?

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 validations used to verify that the request was processed correctly.

Although Latka currently supports only HTTP and HTTPS request/response validations, it may be expanded to perform other sorts of functional testing as warranted.

A simple example of a Latka XML test suite is shown in A Sample Latka Test Suite. When processed, this example would verify that the Jakarta Commons homepage is present and that all the Commons Components have online documenation.

## Installing Latka

Requirements

- JDK 1.3 or better
- (for optional web application) Tomcat 4.0 B7 or better - does not work in Tomcat 3.2, untested in other containers
- (for optional SSL support) Sun JSSE library

General installation

1. Download and uncompress the Latka distribution.
2. If you wish to perform Latka test over SSL, you need to configure your JVM with the Sun JSSE library.

Optional web application installation

1. Copy the "webapp/latka-webapp.war" file from the distribution to the "webapp" directory of Tomcat.
2. If you have already configured log4j for Tomcat, you should remove log4j.jar from the /WEB-INF/lib directory of the Latka webapp.

## Using Latka

### Running the sample tests

Command-line interface

1. Open a command prompt inside the "bin" directory of the distribution.
2. Run the Latka batch script on one of the sample XML test suites:
   latka file:../tests/samples/TestCommonsWebsite.xml

Web application

1. Go to the index page of the Latka web application.
2. Select "Run a test from the server"
3. In the test directory dialog box, enter the directory: <latka distrubution directory>/tests/samples
4. Click on one of the tests to execute it.

### Creating your own tests

(More to come...) Examine the Latka DTD in the conf directory for a list of all available elements. See the samples for typical syntax.

### Running tests

Command-line interface

1. Open a command prompt inside the "bin" directory of the distribution.
2. Run the Latka script with no arguments for information on usage.

Web application

1. Go to the index page of the Latka web application.
2. Select "Run a test from the server"
3. In the test directory dialog box, enter the directory where your tests are located.
4. Click on one of the tests to execute it.

### Creating your custom validations

(More to come...)

## XML Reference

# byteLength

## Name

byteLength — validates the length of an HTTP(S) response

## Synopsis

### DTD

    <!ELEMENT byteLength EMPTY>
    <!ATTLIST byteLength min   CDATA "0"
                          max   CDATA #IMPLIED
                          label CDATA #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`min` | NUMBER | `0` | Minimum number of bytes required for a valid response. Implied. Defaults to `0`.
`max` | NUMBER | none | 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.
`label` | CDATA | none | Label associated with this validation, which may be used in programatically generated documentation or reports. Optional.

## Parents

`validate`

## Description

A `byteLength` validation passes if the HTTP(S) response is at least `min` bytes long, and (when specified) at most `max` bytes long.

# cookie

## Name

cookie — validates the presence of an HTTP(S) cookie in a response

## Synopsis

### DTD

    <!ELEMENT cookie EMPTY>
    <!ATTLIST cookie name  CDATA #REQUIRED
                     value CDATA #IMPLIED
                     label CDATA #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`name` | CDATA | none, but required | The name of the cookie to look for. Required.
`value` | CDATA | none, optional | The value that the cookie with the specified name should have (if any).
`label` | CDATA | none | Label associated with this validation, which may be used in programatically generated documentation or reports. Optional.

## Parents

`validate`

## Description

A `cookie` validation passes if the HTTP(S) response contains a cookie with the specified `name`. If a `value` is provided, the cookie must also have the specified value.

# credentials

## Name

credentials — username/password credentials for Basic HTTP authentication.

## Synopsis

### DTD

    <!ELEMENT credentials EMPTY>
    <!ATTLIST credentials userName CDATA #REQUIRED
                          password  CDATA #REQUIRED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`userName` | CDATA | none, required | User name. Required.
`password` | CDATA | none, required | Password. Required.

## Parents

`request`

## Description

Contains credentials for HTTP Basic Authentication.

# maxRequestTime

## Name

maxRequestTime — validates the response time for an HTTP(S) request

## Synopsis

### DTD

    <!ELEMENT maxRequestTime EMPTY>
    <!ATTLIST maxRequestTime millis CDATA "30000"
                               message  CDATA #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`millis` | NUMBER | `30000` | Maximum amount of time, in milliseconds, in which a response must be returned to be considered a valid response. Implied. Defaults to `30000` milliseconds, or 30 seconds.
`label` | CDATA | none | Label associated with this validation, which may be used in programatically generated documentation or reports. Optional.

## Parents

`validate`

## Description

A `maxRequestTime` validation passes if the HTTP(S) response is obtained in no more than `millis` milliseconds.

# param

## Name

param — indicates a request parameter as part of an HTTP(S) request to be executed

## Synopsis

### DTD

    <!ELEMENT request (paramName, paramValue)>

### Attributes

None.

## Parents

`request`

## Description

A parameter to be submitted as part of a `request`.

# paramName

## Name

paramName — the name part of a name/value pair parameter

## Synopsis

### DTD

    <!ELEMENT paramName (#PCDATA)>

### Attributes

None.

## Parents

`param`

## Description

The name part of `param` to be submitted as part of a `request`.

# paramValue

## Name

paramValue — the value part of a name/value pair parameter

## Synopsis

### DTD

    <!ELEMENT paramValue (#PCDATA)>

### Attributes

None.

## Parents

`param`

## Description

The value part of `param` to be submitted as part of a `request`.

# regexp

## Name

regexp — validates the presence or absence of a regular expression within an HTTP(S) response

## Synopsis

### DTD

    <!ELEMENT regexp EMPTY>
    <!ATTLIST regexp pattern    CDATA          #REQUIRED
                     cond       (true | false) "true"
                     ignoreCase (true | false) "false"
                     label       CDATA         #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`pattern` | CDATA | none, but required. | The regular expression to look for.
`cond` | Enumeration:
`true`
`false`
| `true` | When `true`, the given `pattern` must match within the response. When `false`, the given `pattern` must not match within the response.
`ignoreCase` | Enumeration:
`true`
`false`
| `false` | When `true`, case is ignored within the given `pattern`.
`label` | CDATA | none | Label associated with this validation, which may be used in programatically generated documentation or reports. Optional.

## Parents

`validate`

## Description

A `maxRequestTime` validation passes if the HTTP(S) response is obtained in no more than `millis` milliseconds.

# request

## Name

request — indicates an HTTP(S) request to be executed

## Synopsis

### DTD

    <!ELEMENT request (credentials?, param*, validate?)>
    <!ATTLIST request path   CDATA        #REQUIRED
                      method (post | get) "get"
                      host   CDATA        #IMPLIED
                      port   CDATA        #IMPLIED
                      label  CDATA        #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`path` | CDATA | none, but required | Request path. Required.
`method` | enumeration:
`get`
`post`
| `get` | HTTP method. Implied. Defaults to `get`.
`host` | CDATA | none | Host to submit request to. Optional. When absent, uses default from `suite`.
`port` | NUMBER | depends upon protocol | Port to submit request to. Optional. When absent, uses default from `suite`.
`label` | CDATA | none | Label associated with this validation, which may be used in programatically generated documentation or reports. Optional.

## Parents

`suite`, `session`

## Description

An HTTP(S) request to be executed.

# session

## Name

suite — wrapper for a sequence of `request`s associated with the same state (session)

## Synopsis

### DTD

    <!ELEMENT session (request+)>
    <!ATTLIST session sessionId CDATA #IMPLIED
                      label      CDATA #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`sessionId` | CDATA | none | Unique identifier for this `session`. Sessions with the same `sessionId` will share the same underlying state (e.g., cookies, etc.)
`label` | CDATA | none | Label associated with this `session`, which may be used in programatically generated documentation or reports. Optional.

## Parents

`suite`

## Description

A `session` is a collection of `request`s that share the same underlying state. For example, a cookie that returned in the response to one `request` will be included in subsequent `request`s.

# statusCode

## Name

statusCode — validates an HTTP response code

## Synopsis

### DTD

    <!ELEMENT statusCode EMPTY>
    <!ATTLIST statusCode code  CDATA "200"
                    message CDATA #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`code` | NUMBER | `200` | Numeric HTTP response code to expect. Implied. Defaults to `200`.
`label` | CDATA | none | Label associated with this validation, which may be used in programatically generated documentation or reports. Optional.

## Parents

`validate`

## Description

A `statusCode` validation passes if the HTTP(S) response code for the given request matches the value specified by `code`.

# suite

## Name

suite — root element for a suite of tests

## Synopsis

### DTD

    <!ELEMENT suite ( (session | request)+ )>
    <!ATTLIST suite defaultHost CDATA #IMPLIED
                    defaultPort CDATA #IMPLIED
                    label        CDATA #IMPLIED>

### Attributes

Name | Type | Default | Description
--- | --- | --- | ---
`defaultHost` | CDATA | none | Default hostname for `request`s. Optional.
`defaultPort` | NUMBER | none | Default port for `request`s. Optional.
`label` | CDATA | none | Label associated with this `suite`, which may be used in programatically generated documentation or reports. Optional.

## Parents

None.

## Description

A `suite` is a collection of `request`s and `session`s to execute.

# validate

## Name

validate — indicates the suite of validations to apply to the current `request` (and its response)

## Synopsis

### DTD

    <!ELEMENT validate (byteLength | cookie | maxRequestTime | regexp | statusCode )+>

### Attributes

None.

## Parents

`request`

## Description

Contains the set of validations to apply to the current `request` (and its response).