Three Ways to Set Expectations in XSpec

Attributes and content of x:expect, in brief

When you test XSLT or XQuery code with XSpec, you use the <x:expect> element to declare expectations about the result of exercising the code. This element is how you ask XSpec to verify that the code did what you think it should have done.

Through its attributes and content, the <x:expect> element supports three syntaxes for expressing what you want to verify. Having three options is flexible, but the combinations have the potential to be confusing. This topic provides a short, visual reference for the three syntaxes.

Further discussion and examples are in the official XSpec wiki, in the Expectations section.

(When you test a Schematron schema with XSpec, you can also use the <x:expect> element as described here. But more likely, you’ll rely on easier-to-use elements like <x:expect-assert> and <x:expect-not-assert> that are tailored for Schematron testing.)

Syntax 1: Compare Against Actual Result

To compare your expected result against the entire actual result, omit the test attribute of <x:expect>, and provide the expected result using other attributes or child nodes. The href attribute is mutually exclusive (“XOR”) with child nodes, whereas the sideways “OR” in the schematic means a combination. In case you use <x:label> element instead of a label attribute, the <x:label> element doesn’t count as a “child node” for this discussion.

The verification passes if and only if the expected result equals the actual result. In case the verification fails, the left side of the HTML report shows the actual result.

Examples

• <x:expect label="..." select="'abc'"/> verifies that the complete actual result equals the string, 'abc'.
• <x:expect label="..."><p/></x:expect> verifies that the complete actual result is an empty <p> element.
• <x:expect label="..." select="true()"/> verifies that the actual result is the boolean value, true.

Syntax 2: Compare Against Data Derived from Actual Result

To compare your expected result against some data derived from the actual result, use the test attribute to specify the derivation in the form of an XPath expression. To avoid conflict with Syntax 3, the test expression must evaluate to something other than true or false. You can think of the expression as filtering the actual result or drilling down into it. Provide the expected result as in Syntax 1.

The verification passes if and only if the expected result equals the outcome from evaluating the XPath expression. In case the verification fails, the left side of the HTML report shows the outcome from evaluating the XPath expression.

Examples

• <x:expect label="..." test="substring($x:result, 4, 3)" select="'abc'"/> verifies that the string value of the actual result has 'abc' as a substring, starting from the fourth position.
• <x:expect label="..." test="$x:result/div/p"><p/></x:expect> verifies that the actual result contains a <div> child element that itself contains an empty <p> child element.
• <x:expect label="..." test="$x:result/descendant::meta" select="()"/> verifies that the actual result does not contain any <meta> elements as descendants.

Syntax 3: True/False Condition

To verify an arbitrary true/false condition related to the actual result, use the test attribute to specify the condition in the form of an XPath expression. In Syntax 3, do not provide an expected result, because the true/false condition says it all.

The verification passes if and only if the expression evaluates to true. In case the verification fails, the left side of the HTML report shows the actual result, and it’s up to you to determine why the true/false condition is false for that actual result.

Examples

• <x:expect label="..." test="contains($x:result, 'abc')"/> verifies that the string value of the actual result contains 'abc' anywhere within it.
• <x:expect label="..." test="empty($x:result/descendant::meta)"/> verifies that the actual result does not contain any <meta> elements as descendants (not that the actual result contains an empty <meta> element).
• <x:expect label="..." test="$x:result eq true()"/> verifies that the actual result is the boolean value, true.

Key Takeaways

• In the <x:expect> element, the child nodes and the attributes named href, select, and as all describe the expected result. Meanwhile, the test attribute describes a derivation (Syntax 2) or an arbitrary true/false condition (Syntax 3).
• The schematics above can remind you of answers to questions like, “Does my XPath expression belong in the select or test attribute?” (Answer: If you’re describing the expected result, put the expression in select; if you’re filtering the actual result or expressing a true/false condition, put the expression in test.) and, “Is @as the data type of the actual or the expected result?” (Answer: The expected result.)