This repository controls the rdfa.info website, including the RDFa Test Suite.
Unless otherwise noted, all content in this source repository is released under a public domain dedication. This includes all HTML, CSS, and JavaScript, including all source code and testing files associated with the RDFa Test Suite. At this point in time, the only exception to the public domain dedication are the icons used on the site, which are copyright by Glyphicons and are released under the CC-BY-SA-3.0 license.
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.
The test-suite is implemented using Ruby, Sinatra along with the Linked Data and SPARQL gems. The user interface is implemented in JavaScript using Bootstrap.js and Backbone.js.
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 true or false.
The HTML application is implemented principlly in JavaScript using Backbone.js as a model-viewer-controller, which downloads the test suite manifest and creates a simple user interface using Bootstrap.js to run tests, or get test details.
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_.
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 git@github.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.
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 --host-language, --version, --vocab_expansion, --rdfagraph, and --uri options.
For example, to run with the Ruby RDFa processor, invoke the following:
bin/run-suite bin/rdf-rdfa
Remote endpoints can also be called using either the URL of the processor, or the name of the processor from the processors.json file.
See bin/run-suite --help for more on the test runner.
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.
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:
http://www.w3.org/2012/pyRdfa/extract?uri=http://rdfa.info/test-suite/test-cases/xml/rdfa1.1/0001.xml.
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
- application/xhtml+xml,
- application/xml,
- image/svg+xml, and
- text/html
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, or
original,processor to control the processor output
(see RDFa Core 1.1 Section 7.6.1).
Also, 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:
{
"any23 (Java)": {
"endpoint": "http://any23.org/turtle/",
"doap": "http://any23.org/",
"doap_url": "/earl-reports/any23-doap.ttl"
},
"clj-rdfa (Clojure)": {
"endpoint": "http://clj-rdfa.herokuapp.com/extract.ttl?url=",
"doap": "https://github.com/niklasl/clj-rdfa",
"doap_url": "/earl-reports/clj-rdfa-doap.ttl"
},
"EasyRdf (PHP)": {
"endpoint": "http://www.easyrdf.org/converter?input_format=rdfa&raw=1&uri=",
"doap": "http://www.aelius.com/njh/easyrdf/",
"doap_url": "/earl-reports/easyrdf-doap.ttl"
},
"Green Turtle (JavaScript)": {
"doap": "https://code.google.com/p/green-turtle/",
"doap_url": "/earl-reports/green-turtle-doap.ttl"
},
"java-rdfa (Java)": {
"endpoint": "http://rdf-in-html.appspot.com/translate/?parser=XHTML&uri=",
"doap": "https://github.com/shellac/java-rdfa",
"doap_url": "/earl-reports/java-rdfa-doap.ttl"
},
"librdfa (C)": {
"endpoint": "http://librdfa.digitalbazaar.com/rdfa2rdf.py?uri=",
"doap": "https://github.com/rdfa/librdfa",
"doap_url": "/earl-reports/librdfa-doap.ttl"
},
"pyRdfa (Python)": {
"endpoint": "http://www.w3.org/2012/pyRdfa/extract?uri=",
"doap": "http://www.w3.org/2012/pyRdfa"
},
"RDF::RDFa (Ruby)": {
"endpoint": "http://rdf.greggkellogg.net/distiller?raw=true&in_fmt=rdfa&uri=",
"doap": "http://rubygems.org/gems/rdf-rdfa",
"doap_url": "/earl-reports/rdf-rdfa-doap.ttl"
},
"RDF::RDFa::Parser (Perl)": {
"endpoint": "http://buzzword.org.uk/2012/rdfa-distiller/?format=rdfxml&url=",
"doap": "http://purl.org/NET/cpan-uri/dist/RDF-RDFa-Parser/v_1-097",
"doap_url": "/earl-reports/rdf-rdfa-parser-doap.ttl"
},
"Semargl (Java)": {
"endpoint": "http://demo.semarglproject.org/process?uri=",
"doap": "http://semarglproject.org"
},
"other": {
"endpoint": "",
"doap": ""
}
}
The 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 doap_url
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, public-rdf-wg@w3.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.
The JavaScript and CSS files are minimized into cached assets. Any change to CSS or JavaScript files requires that the assets be re-compiled. This can be done as follows:
rake assets:precompile
Make sure to do this before committing changes that involve any CSS or JavaScript contained within file:public/stylesheets or public/javascripts.