Writing unit tests

Schema development, migration and evolution require you to break or augment graphs. If the consumers of your queries can be characterized by queries, you can record a set of queries and expected results to act as validators. The sparql executable's --compare feature allows you to execute queries, produce results, and compare those results against reference results.

Table of Contents Creating Reference Results Comparing Against Reference Results Mismatches Silent Comparisons Invocation in Makefiles

Creating Reference Results

While the --compare function takes many results formats, probably the simplest to manage is the SRT format, which looks like the standard output from a database query tool like MySQL. To see this format, load sparql with some initial data about itself (-D) and execute a trivial query:

  SPARQL -D -e "SELECT ?s ?p { ?s ?p <http://usefulinc.com/ns/doap#Project> }"

You should see output like:

  +----+---------------------------------------------------+
  | ?s | ?p                                                |
  | <> | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> |
  +----+---------------------------------------------------+

That's an SRT file. You can store the results on a unix system by redirecting the output to a file:

  SPARQL -D -e "SELECT ?s ?p { ?s ?p <http://usefulinc.com/ns/doap#Project> }" > D.srt

Comparing Against Reference Results

You can now run some query (in fact the same query, for our example) and see if you get the same results:

  SPARQL -D -e "SELECT ?s ?p { ?s ?p <http://usefulinc.com/ns/doap#Project> }" --compare D.srt

You should see:

  matched

What if we change the order of the select variables?

  SPARQL -D -e "SELECT ?p ?s { ?s ?p <http://usefulinc.com/ns/doap#Project> }" --compare D.srt
  matched

The SPARQL Results specification makes no distinctions based on selection order, and we follow that precedent.

Mismatches

What if they don't match? Let's query an empty graph and compare that to the results above:

  SPARQL -D -e "SELECT ?p ?s { GRAPH <empty> { ?s ?p <http://usefulinc.com/ns/doap#Project> } }" --compare D.srt
  +----+----+
  | ?p | ?s |
  +----+----+
  !=
  +---------------------------------------------------+----+
  | ?p                                                | ?s |
  | <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> | <> |
  +---------------------------------------------------+----+

The verbose output tells you exactly how the two result sets differ.

Silent Comparisons

If you ask sparql not to display anything, it will return the results via a 0 (success) or 1 (failure) return code. You can't see this directly, but unix shells allow you to execute commands depending on the return value of an earlier call:

  SPARQL -D -qe "SELECT ?p ?s { GRAPH <empty> { ?s ?p <http://usefulinc.com/ns/doap#Project> } }" --compare D.srt ;
  if [ $? -gt 0 ]; then
    echo "D.srt didn't match";
  fi

As expected from the verbose output, this match will fail and we will get:

  D.srt didn't match

while a compare which matches:

  SPARQL -D -qe "SELECT ?p ?s { ?s ?p <http://usefulinc.com/ns/doap#Project> }" --compare D.srt

will leave $? set to 0 (here producing no output).

Invocation in Makefiles

Above, you saw how to invoke --compare from a shell. Testing for failure is somewhat easier in Makefiles:

  SPARQL -D -qe "SELECT ?p ?s { GRAPH <empty> { ?s ?p <http://usefulinc.com/ns/doap#Project> } }" --compare D.srt || echo "D.srt didn't match"