This page demonstrates how to get started with XSpec and XQuery. It runs through a tutorial that executes an XSpec test for XQuery. The examples are in xquery-tutorial.xspec and in xquery-tutorial.xqm.

Make sure that XSpec is installed correctly by running the help message at the end of the installation process:

• Installation on Mac/Linux
• Installation on Windows

The tutorial directory contains an sample of XQuery module xquery-tutorial.xqm to test and its sample XSpec test suite xquery-tutorial.xspec.

The XQuery module to test is specified in the @query-at attribute at the beginning of the XSpec file.:

<x:description xmlns:x="http://www.jenitennison.com/xslt/xspec"
               xmlns:functx="http://www.functx.com"
               query="http://www.functx.com"
               query-at="xquery-tutorial.xqm">

Note also the @query attribute specifies the namespace of the XQuery module.

Navigate to your XSpec directory (e.g., ~/xspec/for Mac/Linux or C:\xspec\ for Windows) and run the XSpec test for XQuery with this command:

For Mac/Linux:

bin/xspec.sh -q tutorial/xquery-tutorial.xspec

For Windows:

bin\xspec.bat -q tutorial\xquery-tutorial.xspec

Note that you invoke the XSpec script with -q option against the XSpec test file (*.xspec), not the XQuery module file (*.xqm). The output in the command line should be similar to this:

Creating XSpec Directory at tutorial/xspec...

Creating Test Stylesheet...

Running Tests...

Formatting Report...
passed: 1 / pending: 0 / failed: 0 / total: 1
Report available at tutorial/xspec/xquery-tutorial-result.html
Done.

Open the HTML report at tutorial/xspec/xquery-tutorial-result.html with your favorite web browser to see the test results. The HTML report should look like this:

Now that you have successfully executed your first XSpec test for XQuery, let's analyze the XQuery and the XSpec test so that you can learn how to write your own tests.

xquery-tutorial.xqm contains an XQuery function which takes a string as its argument. The first character of the string passed to the function is capitalized and concatenated to the rest of the string. Finally, the new string with the first character capitalized is returned to the calling method.

xquery-tutorial.xspec contains the following XSpec scenario for testing the correct behavior of the XQuery function:

<x:scenario label="Calling function capitalize-first">
  <x:call function="functx:capitalize-first">
    <x:param select="'hello'"/>
  </x:call>

  <x:expect label="should capitalize the first character of the string" select="'Hello'"/>

</x:scenario>

The XSpec test invokes the XQuery function via x:call function="functx:capitalize-first" and passes the string hello as parameter. The expected value that should be returned by the function — i.e., the string Hello — is contained in the @select attribute of the x:expect element.