GRDDL Test Cases

Abstract

This document describes and includes test cases for software agents that extract RDF from XML source documents by following the set of mechanisms outlined in the Gleaning Resource Description from Dialects of Language (GRDDL) specification. They demonstrate the expected behavior of a GRDDL-aware agent by specifying one (or more) RDF graph serializations which are the GRDDL results associated with a single source document.

Introduction

A set of test cases is provided as part of the definition of GRDDL. This document presents those test cases. They are intended to provide examples for, and clarification of, the normative behavior of a GRDDL-aware agent. They should be used for testing the conformance of GRDDL-aware agents. The normative tests cover behavior expected of a GRDDL-aware agent.  The informative tests demonstrate other permitted behavior with respect to the issues resolved by the Working Group. This document itself has (as a GRDDL result) a manifest document describing the test cases in RDF.

Deliverables

The deliverables included as part of the test case collection are:

• A recommendation track document which normatively includes the tests
• A manifest RDF/XML document describing the collection of tests
• An example driver for use with testing a particular implementation
• A zip archive including:
  • The input and output(s) for each test
  • The manifest file
  • The test driver

Test Manifest Format

This test collection uses an RDF vocabulary for manifests developed for the RDF Test Cases Recommendation. A GRDDL-aware agent can extract the test collection and automatically test compliance by attempting to reproduce the expected GRDDL result(s) associated with each test case. The output documents are read as if they were retrieved from the URL of the input document. Some input documents have multiple output documents, see below

Using the Test Driver

We provide testft.py, a test driver, written in Python and based on rdflib 2.3.3. Run it a la:

$ python testft.py --run your_grddl_impl testlist1.rdf >earl_out.rdf All tests were passed!

It has options for --debug and such; invoke it with no arguments (or with --help) for details:

Options:
  -r, --run              path to a GRDDL implementation to use to process the 
                         source document (checking results)
  -u, --update           path to a GRDDL Implementation to use to process the 
                         source document
      --tester           The URI of an agent associated with the EARL test assertions.
                         A BNode is used if none is given                          
      --project          The URI of the EARL 'subject' (the implementation being tested).
                         A BNode is used if none is given

The tests do not require the use of this driver

EARL Reporting

In addition to writing various diagnostic messages to STDERR, the test harness writes additional RDF data to STDOUT: an EARL assertion about each test it runs.

To tell it about the person running the tests and the software project being tested, point it to a tester (a URI in a FOAF RDF graph) and a test subject (a URI in a DOAP RDF graph).

Protocol Tracing

We find TCPWatch useful for debugging HTTP protocol interactions. If you start TCPWatch like so:

$ python tcpwatch.py -p 6543 &

then you can use it as a proxy:

$ http_proxy=http://127.0.0.1:6543 python testft.py --run your_grddl_impl testharness.rdf

Local Policies, Faithful Rendition, and Conformance

The GRDDL specification states that any transformation identified by an author of a GRDDL source document will provide a Faithful Rendition of the information expressed in the source document. The specification also grants a GRDDL-aware agent the license to makes a determination of whether or not to apply a particular transformation guided by user interaction, a local security policy, or the agent's capabilities. However, for the purpose of running these tests in order to determine compliance, a GRDDL-aware agent with a security policy which does not prevent it from applying transformations identified by each test will produce the GRDDL result associated with each test.

Tests with Multiple GRDDL Results

Certain tests have multiple GRDDL results as a direct consequence of Faithful Infoset considerations, information resources with multiple representations, and seperate GRDDL mechanisms which produce distinct GRDDL results. For such tests, A GRDDL-aware agent should output at least one of the GRDDL results associated with the test case.

Normative Tests

Each test has an input document and an output document. the output document is an RDF/XML document and represents a GRDDL result of the input document.

Informative Tests

These tests cover features not mandated explicitely by the GRDDL specification, but demonstrate behavior expected of a GRDDL-aware agent in the context of Web Architecture best practices (@@Appropriate [WEBARCH] link?). They also cover behavior suggested by the Working Group as a result of resolving certain issues.

@@TODO: How to reconcile current (approved but informative) status of the Atom / Turtle test? - There was appreciable consensus on mentioning RDF graphs not RDF/XML documents

• #atomttl1: re issue issue-output-formats yes, transformations may produce serializations other than RDF/XML; see 26 Nov from Danny and Henry input, output.

  Note the transformation, atom2turtle_xslt-1.0.xsl, gives an RDF graph using turtle rather than RDF/XML. This test uses the text/rdf+n3 media type, which should appear in the IANA list of text media types in due course. See also the SPARQL CR request of Apr 2006.

  See also: Atom/RDF in progress Aug 2006 by David Powell.

  APPROVED in 24 Jan discussion of #issue-output-formats

• Content Negotiation with GRDDL (1 of 2) input output

  This test exists to bring attention to developers to issues of content negotiation, in particular, content negotiation over language as described and implemented by W3C QA. There are two valid resulting GRDDL results of running this GRDDL transformation depending on what language the GRDDL-aware agent uses, and an implementation of a GRDDL-aware agent only needs to retrieve the one that is appropriate for its HTTP header request. This result follows from retrieving a English version of the HTML representation and thus having the GRDDL result produce a result with English-language content.

  issue-mt-ns

• Content Negotiation with GRDDL (2 of 2) input output

  See the explanation of having two valid outputs for this test case. This result follows from retrieving a German version of the HTML representation and thus having the GRDDL result produce a result with German-language content.

  issue-mt-ns

• #httpHeaders: test the use http headers to define a transform by jjc, uploaded by bwm Feb 19, 2007. Note that a .htaccess file is used to generate the required headers.
  input, output

  @@What is the status of this scenario?

References

@@Need references

Normative

Informative