Contents

• Contents
• Introduction
• Requirements
• Installation
• Your First Test Suite
• Running a Test Suite
• Working With XSpec Documents
• Tips

Introduction

This page demonstrates how to download, install, and use XSpec. It also runs through testing an XSLT stylesheet. The examples are in the tutorial directory of the XSpec download (note: this directory is not part of the release yet, you have to use the Subversion trunk for now, waiting for the next release, or just use the files directly from here).

Requirements

XSpec requires the Saxon XSLT and XQuery processors. You probably already have them, but if you don't, get them from here.

Installation

To get started:

1. Download the current version of XSpec from the download page. Unzip the archive somewhere accessible. For this tutorial we'll assume that XSpec is in c:\xspec\ directory (Unix users can translate this.).
2. Open xspec.bat in your favorite text editor. Change the value on line 3 to the location of your saxon jar (Unix users need to set the environment variable $SAXON_HOME).
3. Open up a command prompt. Navigate to the XSpec executable directory, and test the batch script:

> xspec.bat

You should get a usage summary:

 Usage:
   xspec filename [coverage]
     filename should specify an XSpec document
     if coverage is specified, outputs test coverage report

Your First Test Suite

Now that we have XSpec installed, we're ready to try it out. XSpec comes with a sample of XSLT stylesheet to test and its sample test suite, both of which are in the tutorial directory.

If you want to have a look at them online, you can view them directly from the repository: the tested stylesheet and the sample test suite.

Running a Test Suite

First, Copy the c:\xspec\tutorial subdirectory somewhere where you can work in it. For the purposes of this tutorial, we'll say it's in c:\home\tutorial\. Navigate to that directory and run the command:

> c:\xspec\xspec.bat escape-for-regex.xspec

If everything works correctly, an HTML report will appear in your browser. The output in the shell should look like this:

C:\home\tutorial>c:\xspec\xspec.bat escape-for-regex.xspec
Creating Test Stylesheet...
"C:\home\tutorial\xspec\escape-for-regex.xsl"
escape-for-regex.xspec

Running Tests...
Testing with SAXON 9.1.0.8
No escaping
Must not be escaped at all
Test simple patterns
..When encountering parentheses
escape them.
..When encountering a whitespace character class
escape the backslash
result should have one more character than source
When processing a list of phrases
All phrase elements should remain
String should be escaped and status attribute should be added
      FAILED

Formatting Report...
passed: 5 / pending: 0 / failed: 1 / total: 6
Done.

And the HTML report should look like this:

If you got an error, check to make sure that the path to the saxon jar is correct. If you are still having issues, ask for help on the XSpec mailing list.

As you can see, one of the tests has failed. We'll come back to that. For now, note that you invoke the XSpec script against the test, not the stylesheet. The stylesheet filename is specified on the /x:description/@stylesheet attribute in the XSpec document.

If everything worked, there should be a new xspec subdirectory in c:\home\tutorial\ (or your equivalent). It contains three files generated by XSpec:

• escape-for-regex.xsl The XSpec test in XSLT form.
• escape-for-regex-result.xml The test results in XML format.
• escape-for-regex.html The human-readable HTML test report. Most of the time, this is the only file out of these three that you'll care about.

For more information about how the XSpec tests are run, see RunningScenarios.

Working With XSpec Documents

Open escape-for-regex.xslt and escape-for-regex.xspec in your favorite XML editor. The transform has a single function and a couple of templates that we're testing.

The XSpec document has three top-level scenarios, which are contained in `

<scenario>

</scenario>

's. The first two test the function, and the third tests the matching templates.

The first scenario is simple; it just calls the function functx:escape-for-regex() with the given parameter value and directly compares its result to our expected result. A function is tested by using an <x:call/>, passing it a parameter using an <x:param/>. Our expectations about how the functions should behave are captured by <x:expect/>s.

Scenarios can be nested -- and the second top-level scenario is, containing two scenarios that test two aspects of the function functx:escape-for-regex(). The first nested scenario is an equality test, just like the first-top level scenario. The second nested scenario is more interesting -- it tests the output of a function against an XPath expression given in @test. Note that we can have as many expectations as we like within a scenario.

The third top-level scenario tests the templates in the transform. An <x:context/> contains a nodeset we want to apply templates to. It has two expectations -- the first a simple XPath test, and the second demonstrates how we can directly compare a nodeset to the output by including the nodeset as descendants of an <x:expect/>.

Although it's not shown here, both <x:context/> and <x:call> have optional @href and @select attributes, which can be a very powerful way to define tests. @href is used to point to an external document, and @select is used to select certain nodes to test against.

For a more detailed description of how a XSpec document is put together, see WritingScenarios.

One of the tests failed, so let's fix it. When a test fails in XSpec, the report shows both the actual result and the expected result side-by-side, with differences highlighted in red. From this report, we can see that the failed scenario is labeled "When processing a list of phrases" and the specific expectation that failed is labeled "Strings should be escaped and status attributes should be added." The difference is that the @status attributes contain the wrong values. Change line 35 of the transform to read:

   <phrase status="{if (. = $escaped-text) then 'same' else 'changed'}">

Save the transform, and re-run the XSpec test. All tests should be green:

Tips

There are many ways to integrate XSpec into your workflow. Here are a few tips:

• Add the XSpec executable directory to your system path.
• By default, XSpec stores its result documents in the subdirectory "xspec" of the folder where the particular stylesheet that you are testing resides. You may want to change the variable TEST_DIR to the system temporary folder: SET TEST_DIR=%TEMP%\xspec. This works well when you are integrating the XSpec with Oxygen and don't want to clutter up your project folders with XSpec results.
• Integrate XSpec into Oxygen XML editor.
• Install the Oxygen framework for XSpec.
• Customize Emacs to use the XSpec schema with XSpec files.