$Id: README,v 1.1 2007-01-26 12:25:45 mike Exp $


Overview
========

This directory contains test-cases of Keystone Resolver.  Each
test-case is represented by a pair of files with a shared basename,
one with the extension ".in", and the other with ".out".  Each ".in"
file has the following format:

* Leading whitespace is discarded.
* Lines beginning with hash ("#") are comments, and so ignored.
* Lines consisting only of whitespace are ignored.
* The first significant line is a set of OpenURL parameters.

And the corresponding ".out" file contains the output -- usually but
not always an XML document -- expected to be generated by Keystone
Resolver for the specified parameters.

The parameters are expressed as a single URL-encoded string: that is,
precisely the sequence of characters that follows the BASE-URL part of
the actual OpenURL.  To make such a sequence, just generate an OpenURL
from the source of your choice, and chop off the leading
	http://<host>[:<port>]//
portion, and leave the rest untouched.

To these parameters are added the single additional non-stamdard
parameter "opt_xml=1", which requests Keystone Resolver to emit the
XML it generates directly, and not pass in through an XSLT engine to
generate HTML as in normal operation.  The result of this is a set of
HTTP headers and a blank line (all of which we ignore) followed by an
document that is compared with the one specified in the ".out" file.


Provenance of Test Cases
========================

The test-cases briefly describe their own provenances.  More detail is
provided here.

OpenURL v0.1 standard (files: standard-0.1-*)
---------------------------------------------

Examples taken from the OpenURL 0.1 standard use the version of that
standard downloaded from
	http://www.openurl.info/registry/docs/pdf/openurl-01.pdf
which is also included in this distribution as ../../openurl-01.pdf

Zetoc (files: zetoc-*)
----------------------

Examples taken from Z39.50 Electronic Table of Contents (Zetoc) were
obtained as follows:
* Go to http://zetoc.mimas.ac.uk/zetoc/wzgw?f=f&form=general&id=1014407
* Perform the search described in the individual test-case
* Click through the "More information" near at the bottom of the
  full-record display page.
The "More information" link is to a Zetoc-local script, but it
redirects to an OpenURL.

Openly Test Suite (files: openly-*)
-----------------------------------

Examples taken from Openly Informatics' OpenURL 1.0 Test Suite can be
found on the enormously useful hand-authored test-suite page at
	http://isi.1cate.com/t/test/niso-suite-10.html
Many of these are lifted directly from the text of the standard
itself.

Feature Tests (files: feature-*)
--------------------------------

These are OpenURLs that I made up myself specifically to exercise a
particular code-path within the resolver.

Failure-Report Tests (files: fail-*)
------------------------------------

These are OpenURLs that I made up myself specifically to check that
certain kinds of failure are detected and reported appropriately.


