RDFa Test Suite
The RDFa Test Suite is a set of Web Services, markup and tests that can be used to verify RDFa Processor conformance to the set of specifications that constitute RDFa 1.1. The goal of the suite is to provide an easy and comprehensive RDFa testing solution for developers creating RDFa Processors.
The RDFa Test suite allows developers to mix and match RDFa processor endpoints with different RDFa versions and Host Languages.
The RDFa Test Suite is an HTML application driving the entire process.
The RDFa Test Suite drives the entire process. The first step is to retrieve the list of tests associated with different RDFa versions and host languages. Then the RDFa Test Suite requests the RDFa Service endpoint to run the associated SPARQL query, which uses an ASK form to return true or false, and a FROM clause to identify a result document. The built-in SPARQL processor will poke the URL, referencing the chosen processor endpoint with a query parameter indicating the test document, and other parameters used to control the processor.
Ruby/Sinatra is responsible for running the service, which provides the test files, launches the HTML application, and executes SPARQL queries on request from the HTML app. The SPARQL queries, in turn, are access the processor endpoint to create a graph against which the query is run, with the results returned to the HTML app as a JSON
Processing happens in the following order:
RDFa Test Suite | RDFa Service | RDFa Processor load webpage -> <- test scaffold load manifest -> <- JSON-LD manifest run test -> Load SPARQL query with FROM referencing processor and reference to test document. -> Process referenced test document and return RDF with Content-Type indicating <- format. SPARQL runs with returned document returning _true_ display results <- or _false_.
Running the test suite
You can view and run this test suite at the following URL:
The website may be run locally and access either local or remote services. The site is implemented as a Ruby/Sinatra application compatible with [Rack] interfaces, similar to Ruby on Rails. On a production installation, this is usually done with Apache and Passenger. Locally, it can be run using rackup or shotgun.
Running the website locally should be as simple as the following:
git clone email@example.com:rdfa/rdfa-website.git cd rdfa-website [sudo] gem install bundler bundle install rackup
This will create an instance, usually running on port 9292. If you access as http://localhost:9292/test-suite/, it will re-write test URIs to http://rdfa.info/test-suite/ so that processors can see any tests that are already uploaded. If you want to run with a local endpoint, run with something else such as http://127.0.0.1:9292/test-suite/, which will inhibit the URI rewriting. Note that you might have to create config.ru manually, you can just copy the existing config.ru.sample.
Command line runner
By implementing a command-line runner, the tests can be run using bin/run-suite. This allows a processor that does not implement an HTTP-based distiller to run through test cases using a shell command.
To use this, implement a shell command accepting input RDFa on standard input generating Turtle or N-Triples on standard output. It should also accept the
For example, to run with the Ruby RDFa processor, invoke the following:
Remote endpoints can also be called using either the URL of the processor, or the name of the processor from the
See bin/run-suite --help for more on the test runner.
How to add a unit test
In order to add a unit test, you must follow these steps:
- Pick a new unit test number. For example - 250. To be consistent, please use the next available unit test number.
- Create a markup file in the tests/ directory with a .txt extension. For example: tests/250.txt
- Create a SPARQL query file in the tests/ directory with a .sparql extension. For example: tests/250.sparql
- Add your test to manifest.ttl and indicate the host language(s) and version(s) for which
it applies. For example, if you would like your example to only apply to HTML4,
you would specify
rdfatest:hostLanguage "html4";in the test case entry.
There are three classifications for Unit Tests:
- required - These are tests that are required for proper operation per the appropriate RDFa specification.
- optional - These are tests for optional features supported by some RDFa Processors.
- buggy - These are tests that are buggy or are not considered valid test cases by all RDFa processor maintainers.
The test suite is designed to empower RDFa processor maintainers to create and add tests as they see fit. This may mean that the test suite may become unstable from time to time, but this approach has been taken so that the long-term goal of having a comprehensive test suite for RDFa can be achieved by the RDFa community.
When running locally, after adding a unit test, run
rake cache:clear to remove cached files and ensure that necessary HTTP resources are regenerated. For the deployed website, this happens automatically each time a Git commit is pushed to the server.
How to create a processor endpoint.
The Test Suite operates by making a call to a processor endpoint with a query parameter that indicates
the URL of the test document to be processed. Within the test suite, a text box (upper right-hand corner)
allows a processor endpoint to be selected or added manually. It is presumed that the endpoint URL ends
with a query parameter to which a test URL can be appended. For example, the pyrdfa endpoint is
defined as follows:
http://www.w3.org/2012/pyRdfa/extract?uri=. When invoked, the URL of an actual
test will be appended, such as the following:
Everything required by a processor can be presumed from the content of the document provided, however
the test suite will also set a
Content-Type HTTP header appropriate for the document provided, these include
- image/svg+xml, and
The processor is called with HTTP Accept header indicating appropriate result formats (currently,
text/turtle (indicating Turtle),
application/rdf+xml (indicating RDF/XML), and
text/plain (indicating N-Triples)), and the processor may
respond with an appropriate RDF format. Processors SHOULD set the HTTP
Content-Type of the resulting
document to the associated document Mime Type.
In some cases, the test suite may add additional query parameters to the endpoint URL to test different
required or optional behaviors, these include
rdfagraph, taking a value of
original,processor to control the processor output
(see RDFa Core 1.1 Section 7.6.1).
vocab_expansion taking any value is used
to control optional RDFa vocabulary expansion
(see RDFa Core 1.1 Section 10.2).
To add a processor to the test suite, add to the object definition in
processors.json in alphabetical order. This is currently defined as follows:
doap is the IRI defining the processor. It should be an information resource resulting in a
DOAP project description, and will be used when formatting reports.
If the DOAP project description location differs from the identifying IRI, set that location in
Test cases are provided with HTTP ETag headers and expiration values. Processors MAY cache test case documents but MUST validate the document using HTTP HEAD or conditional GET operations.
The test suite is termed Crazy Ivan because of an unusual maneuver popularized in The Hunt for Red October and Firefly. It is a term used to detect problems that are hiding, which is what the test suite.
Seaman Jones: Conn, sonar! Crazy Ivan! Capt. Bart Mancuso: All stop! Quick quiet! [the ships engines are shut down completely] Beaumont: What's goin' on? Seaman Jones: Russian captains sometime turn suddenly to see if anyone's behind them. We call it "Crazy Ivan." The only thing you can do is go dead. Shut everything down and make like a hole in the water. Beaumont: So what's the catch? Seaman Jones: The catch is, a boat this big doesn't exactly stop on a dime... and if we're too close, we'll drift right into the back of him.
If you would like to contribute a to the website, include an additional test suite processor endpoint, contribute a new test or to a fix to an existing test, please follow these steps:
- Notify the RDFa mailing list, firstname.lastname@example.org, that you will be creating a new test or fix and the purpose of the change.
- Clone the git repository: git://github.com/rdfa/rdfa-website.git.
- Make your changes and submit them via github, or via a 'git format-patch' to the RDFa mailing list.
Optionally, you can ask for direct access to the repository and may make changes directly to the RDFa Website source code. All updates to the test suite go live within seconds of pushing changes to github via a WebHook call.
Caution: Cached assets