Introduction to XSpec
What does XSpec do?
An XSpec file answers three questions: What do we call? What input do we give it? What should come back? XSpec runs the tests and compares the actual results with the expected ones. It supports XSLT, XQuery, Schematron and, in the version used here, XProc.
Here is a small example. A function should turn column number 27 into the Excel column name AA. We do not need a complete spreadsheet or an office application to check that. We just call the function and compare its return value:
examples/04-columns/column-name.xspec
<x:scenario xmlns:x="http://www.jenitennison.com/xslt/xspec"
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:f="urn:example:columns"
xmlns:e="urn:example:errors" label="Column 27 is AA">
<x:call function="f:column-name"><x:param select="27"/></x:call>
<x:expect label="Return AA" select="'AA'" result-type="xs:string"/>
</x:scenario>x:call calls the function, x:param supplies the number, and x:expect describes the expected result. The f prefix belongs to our example library. The full file in the download also declares the namespace and points to the stylesheet.
That gives us a test for one specific job. If a later change makes the function return something other than AA, the test catches it. Further inputs can be added as further scenarios.
Where did XSpec come from?
XSpec was started by Jeni Tennison and developed further together with Florent Georges. RSpec, from the Ruby world, provided the inspiration for describing expected behavior in readable scenarios. XSpec draws on behavior-driven development, or BDD. To get started, the useful idea is simple: a test should make it clear what the code is supposed to do.
The project was initially hosted on Google Code and later moved to GitHub. Active development resumed in 2016. At data2type, we used XSpec in a training session back in 2013. We return to two exercises from that session here: paragraph initials and Excel column names. The examples have been reworked for this package.
Which version do the examples use?
The package uses XSpec 4.0.3, released on 19 June 2026. It was the latest stable release when versions were checked on 21 September 2026. The 4.0 series adds tests for custom XProc 3 steps. Version 4.0.3 fixes issues in Schematron tests and XSLT coverage and includes SchXslt2 1.11.1.
Using a fixed version makes the examples easier to repeat. Some online documentation already describes features planned for version 4.1, so not every example there can be used unchanged with 4.0.3.