mustrd

Spec-By-Example for RDF & SPARQL

Test your SPARQL queries and transformations with precision, using Given-When-Then principles.

# One spec. Given data. When query. Then result.
:my_test
    must:given [ a must:FileDataset ;
                 must:file "test/data/given.ttl" ] ;
    must:when  [ a must:TextSparqlSource ;
                 must:queryText "CONSTRUCT { ?s ?p ?o }
                                WHERE { ?s a ex:Person ; ?p ?o }" ;
                 must:queryType must:ConstructSparql ] ;
    must:then  [ a must:FileDataset ;
                 must:file "test/data/expected.ttl" ] .

Define your data, run your query, check the result. All in Turtle.

What mustrd is

A pytest plugin

Add --mustrd to your pytest command. Specs become tests. Results show in your runner, CI, and VS Code.

Triplestore agnostic

Run specs against embedded RDFLib, GraphDB, or Anzo. Same specs, different engines. Swap with configuration, not code.

Spec-By-Example

Inspired by Cucumber. Define concrete examples of what your query should do, not abstract assertions about what it might.

Not SHACL

SHACL validates data structure. mustrd validates data transformations. Your query produces the right triples? mustrd checks.

Given-When-Then

Every spec follows the same shape. Load data, run a query, check the output.

Given

The input dataset. A Turtle file, inline statements, an Anzo graphmart, or inherited state.

must:given [
  a must:FileDataset ;
  must:file "data/input.ttl"
] ;

When

The SPARQL action. Inline text, a file reference, or a query builder source. SELECT, CONSTRUCT, or UPDATE.

must:when [
  a must:FileSparqlSource ;
  must:file "sparql/enrich.rq" ;
  must:queryType must:UpdateSparql
] ;

Then

The expected result. An RDF graph, a table of bindings, CSV/Excel, or an empty result.

must:then [
  a must:FileDataset ;
  must:file "data/expected.ttl"
] .

Query types

mustrd validates across SPARQL's full query surface.

Type	What it does	Result compared as
SELECT	Return variable bindings	Table (pandas DataFrame)
CONSTRUCT	Build an RDF graph	Graph isomorphism
UPDATE	INSERT/DELETE triples	Modified graph comparison
ASK	Boolean existence check	True/false
DESCRIBE	Describe a resource	Graph isomorphism

Triplestore support

Write specs once. Run them against any supported engine.

Engine	Protocol	Notes
RDFLib	Embedded (in-memory)	Default. No server needed. Zero config.
GraphDB	HTTP SPARQL endpoint	Repository-based. Optional named graphs.
Anzo	HTTP REST API	Graphmart layers, query builders, AnzoGraph.

Flexible datasets

Givens and thens support multiple data formats.

Type	Description
FileDataset	RDF file — Turtle, NTriples, N3, RDF/XML, TriX
StatementsDataset	Inline reified RDF statements in the spec
TableDataset	Inline tabular bindings for SELECT results
OrderedTableDataset	Tabular data with row ordering (ORDER BY)
FolderDataset	File path passed as a runtime argument
EmptyTable / EmptyGraph	Expect no results
InheritedDataset	Keep existing graph state (chain specs)

VS Code integration

Specs appear as tests in the Test Explorer. Click to run, see diffs on failure.

// settings.json
{
  "python.testing.pytestArgs": [
    "--mustrd",
    "--md=junit/github_job_summary.md",
    "--config=test/test_config_local.ttl"
  ]
}

Reports that are data

A run's output is RDF first: DQV quality measurements over your ontology, a per-term breakdown, competency-question assertions, and a result per test — all with stable IRIs, so runs merge and diff in a triplestore.

The HTML report is rendered from that graph, in the browser, by a single self-contained file. No build step, no CDN, no server: attach it to a CI run or open it from disk. Drop another run's .ttl onto the page to load it.

A run report, driven entirely by the RDF it carries. Open the real thing — it is one file, so View Source is the whole story.

See a live example report · the coverage vocabulary

Two ways to run

The same engine, the same configuration file, the same reports. Pick whichever fits where you are.

As a pytest plugin

Specs become tests in your existing suite, so they run in CI and appear in the VS Code Test Explorer next to everything else.

pip install mustrd

pytest --mustrd \
  --config=mustrd-config.ttl \
  --viewer=report.html

As a command

No pytest. Useful in a pipeline step, a pre-commit hook, or anywhere a test runner would just be in the way. Exits non-zero if a spec fails.

pip install mustrd

mustrd run    --config mustrd-config.ttl
mustrd report --config mustrd-config.ttl \
  --viewer report.html

mustrd run executes the specs and prints a result table. mustrd report does the same and writes the artefacts you ask for — --viewer for the HTML page above, --md for Markdown, --term-coverage-rdf / --results-rdf for the graph itself. Both take the same flags as the plugin.

Status

RDFLib executor: stable
SELECT / CONSTRUCT / UPDATE specs: stable
SHACL spec validation: stable
pytest plugin with VS Code: stable
GraphDB integration: stable
Anzo integration: stable
Markdown test reports: implemented
GitHub Actions CI summary: implemented
RDF run output (coverage, CQs, per-test results): implemented
Self-contained HTML report viewer: implemented
mustrd CLI (run & report without pytest): implemented

Get started

pip install mustrd

pytest --mustrd --config=test/mustrd_configuration.ttl