Integrating Your Own Test Helpers - xspec/xspec GitHub Wiki

x:helper allows you to integrate your own test helper modules into the test runner. For example, you can write one or more x:helper lines like this

XSLT:

<x:description ...>
  <x:helper stylesheet="helper.xsl" />
  ...

XQuery:

<x:description ...>
  <x:helper query="helper"
            query-at="helper.xqm" />
  ...

and then the public functions or the global variables implemented in helper.xsl (XSLT) or helper.xqm (XQuery) can be used in XSpec.

For example, if a test requires complex verification, you may write a helper function, my:verifier(), in helper.xsl:

<xsl:stylesheet ...>
  <xsl:function name="my:verifier" as="xs:boolean">
    <xsl:param name="actual-result" />
    ...perform complex verification on $actual-result and return success/failure...
  </xsl:function>
</xsl:stylesheet>

and use it in x:expect/@test:

<x:description>
  <x:helper stylesheet="helper.xsl" />
  <x:scenario label="...">
    ...
    <x:expect label="Defer verification to a helper function"
              test="my:verifier($x:result)" />

XSLT ignores x:helper[@query]. XQuery ignores x:helper[empty(@query)]. You cannot use XSLT helpers from XQuery, and vice versa.

The test runner imports your helper modules after importing the test target module. In consequence, your helper modules become integral parts of the testing environment:

• Helper templates are applied to the context set up by x:context (in case of matching scenarios)

• Helper stylesheets can override the test target stylesheet.

  • For example, if you want to change the behavior of the test target for the purposes of unit testing, you can write some templates in a helper stylesheet and override the test target stylesheet. That's exactly the same as what you usually do using xsl:import.
  • Make sure your helper module fulfills only a specific and limited purpose. Otherwise, your helper may produce adverse side effects on the behavior of the test target and make your tests misleading. Likewise, the test target may also have side effects on your helper and you may need to protect the helper against it (example).

x:helper is a rather new feature (v2.0) and its details are subject to change. Any feedback is welcome.

Helper XSLT Packages

You can specify XSLT packages in x:helper.

<x:description ...>
  <x:helper package-name="http://example.org/helper-package"
            package-version="1.0" />
  ...

Specifying an XSLT package will just insert the equivalent <xsl:use-package> in the test runner. To make the inserted <xsl:use-package> work, the user should set up a Saxon configuration and specify the package information in it. The Saxon configuration is usually set up by SAXON_CUSTOM_OPTIONS (CLI) or saxon.custom.options (Ant).

x:helper and @run-as="external"

When /x:description/@run-as is external, the effect of x:helper is limited compared to the default mode (@run-as="import"). The test helper module and the test target module are independent from each other.

• Helpers do not work in x:call/(@function|@template).
• Helper templates are not applied to the context set up by x:context.
• Helpers do not affect the test target.