catalog

Denotes the root element of the catalog document. The catalog lists all test-sets that are to be run and also contains an environment of assorted schemas and source documents.

environment

Denotes an element which defines an assorted list of schemas and sources documents available to test cases. For definition of schemas the test drivers should assume a dependency on schema-awareness.

In addition the environment may set further information about the static context for running the test.

An environment can be made globally available across all test-sets, or within a particular test-set or within a test-case. Locally-defined environments are considered to have precedence over environments defined at some ancestor node, therefore conflicts are avoided.

An environment that is shared between test cases always has a name (given by its name attribute). An environment element within a test case may either be a reference to a shared environment (identified by its ref attribute) or a locally-defined environment (with no name or ref attributes.

static-base-uri

An element used to supply the static base URI for a query. The uri attribute should be an absolute URI.

In the absence of this element, or of a base URI declaration in the query prolog, the static base URI of a query is the file containing the text of the query.

The value uri='#UNDEFINED' indicates that the test expects the static base URI to be absent.

collation

An element which defines a collation URI used in the query.

The uri attribute is the collation URI as it actually appears in the XPath expression. There is a small enumerated set of collation URIs that may appear in tests; these have a meaning that is defined in the test suite. In addition, from 3.1 onwards, URIs in the Unicode Collation Algorithm family can be used. If the implementation cannot bind arbitrary URIs to collations, it may substitute this URI in the source expression by a different one having the same semantics. If the implementation does not support the semantics of the collation, then it should not run the test (support for collations other than the codepoint collation is not a conformance requirement.

The default attribute indicates whether this collation is to be used as the default collation.

decimal-format

The decimal-format element allows a decimal format to be defined as part of the static context for evaluating an XPath expression that calls the format-number() function.

When the decimal-format element is used in an environment, the test expression will always be a simple XPath expression. If the test is to be run using an XQuery processor, the decimal format can be added to the static context either by using the processor's API, or by constructing a query prolog containing a declare decimal format declaration and prepending this to the test expression.

The mechanism is used for testing the format-number() function. As such, the decimal format being defined should always be valid. Tests for invalid decimal formats should be written as XQuery tests with an explicit query prolog (or the equivalent in XSLT).

Test Catalog006 ensures that the decimal-format element is only used in tests that are pure XPath expressions.

param

An element within an environment that declares a variable that can be referenced within test expressions that use this environment.

The value to be bound to the variable is given in the select attribute, which should be a simple XPath expression - typically a literal, or a simple call on a constructor function.

The test expression may or may not include a declaration of the variable (so it can be executed if appropriate using XPath). The "declared" attribute will be present with the value "true" if the variable is declared in the query prolog. The test driver can add a declaration of the variable to the query prolog if required. If the test expression includes the string "(:%VARDECL%:)" then the variable declaration should be added to replace this string; if it does not include this string, the variable declaration can be added at the start.

context-item

An element within an environment that declares the value of the context item for a query.

The value to be bound to the variable is given in the select attribute, which should be a simple XPath expression - typically a literal, or a simple call on a constructor function.

The query is called with the value of the select expression as the context item.

collection

Represents a collection accessible to the collection() function.

The uri attribute identifies the collection URI. If this is absent or zero-length, the collection acts as the default collection, used when no URI is supplied to the collection() function.

The contained source elements identify the documents making up the collection.

function-library

An element which provides access to a function library defined for xslt and xquery.

namespace

When this element is present in an environment, queries using this environment must have a namespace binding in the static context that binds the specified prefix to the specified namespace URI.

A zero-length prefix denotes the default namespace for elements and types.

All tests using an environment that contains a namespace element will be simple XPath expressions, so that the test can be run either under XPath or XQuery. If the test is run using an XPath processor, the namespace must be declared externally using the processor's API. If it is run using an XQuery processor, the namespace can either be declared externally using the processor's API, or a "declare namespace" declaration can be added to the query prolog. Because the test is guaranteed to be a simple XPath expression, adding the namespace declaration at the start is straightforward.

Test Catalog005 checks that no test that requires XQuery uses an environment that contains a namespace element.

query

The content of the element is an XQuery expression to be evaluated. This should return a sequence equivalent to the contents of a sequence which can used as input to test cases. Specifically used in fn:collection. The scope of the <query> element is the parent <collection> element in which it appears.

For example: unparsed-text-lines('xxx')!parse-json()

schema

An element which provides information about a schema to be used to validate a source document. The scope of the <schema> element is the parent <environment> element in which it appears. The test drivers should assume a dependency on schema-awareness.

schemaType

The type definition for the schema element

source

An element which provides information about a source xml file used as input to test cases.

The role and uri attributes indicate how the source document is made available to queries (as the context item, as the value of an external variable, or as a URI that can be supplied to the doc() function.)

The file attribute gives the relative location of the file containing the XML source.

The scope of the <source> element is the parent <environment> element in which it appears. A validated source document references the schema, which maps to the @id of the Schema element.

sourceType

defines the type of the source element.

resource

An element which provides information about a file that can be read as text, used as input to test cases.

The uri attributes indicate how the resource is made available to queries (as a URI that can be supplied to the unparsed-text(), unparsed-text-lines() and unparsed-text-available() functions.)

The file attribute gives the relative location of the file containing the resource.

The optional media-type attribute gives the media type of the resource.

The optional encoding attribute gives the name of the encoding of the resource.

The scope of the <resource> element is the parent <environment> element in which it appears. A validated source document references the schema, which maps to the @id of the Schema element.

resourceType

defines the type of the resource element.

description

An element which provides descriptive information about the resource described by its parent element.

test-set

denotes an element which provides a sequence of test-case entries for a particular function. Within this element we provide data needed to run the test for that function.

dependency

Indicates a dependency which must be satisfied in order for a test to be run.

A dependency may be associated with an individual test case or with a test-set. A dependency at the level of a test-set appplies to all test cases in that test-set.

The attribute setting satisfied="false" indicates that the test should only be run if the dependency is NOT satisfied.

The set of recognized values appearing in the value attribute depends on the content of the type attribute.

The most commonly-used dependency is on the version of XPath or XQuery. This is represented by a dependency with type="spec" whose corresponding value is, for example value="XQ10+ XP30+" which indicates that the test can be run with XQuery 1.0 or later, or XPath 3.0 or later. A test with value="XQ10" should be run with an XQuery 1.0 processor only (typically, an XQuery 3.0 processor will produce a different result, described in a separate test case.)

test-case

denotes an element that contains a test that must be run in a named environment, also contains the expected result and description of the test, including author and creation date.

test

The content of the element is an XPath or XQuery expression to be evaluated.

As an alternative to providing the content inline, it may be provided in an external file referenced using the file attribute. This is done only exceptionally, where (a) the query is unusually large, or (b) there is a need to test features that can only be achieved with an external file, for example special encodings.

created

Provides details of the author and creation date of a test case, source document, schema, etc.

modified

Provides a record of changes made to a test case or other resource over time.

module

Defines an XQuery library module imported by a test case. The module element gives the module URI and the location of the module. The query will contain an "import module" declaration referencing the same module URI, with no "at" location (except where the "at" attribute is being specifically tested, in which case the results are undefined.)

result

denotes an element which provides an <assert> or >error< element pertaining the expected result. Alternatively assertions can appears as a list within <any-of> or <all-of> element. The meaning of these elements are self explantary.

complexType for a sequence of assertions

any-of

denotes an element which provides a list of assertions. One or more of the assertions needs to prove true for the test to pass, but if all fail then the test fails.

all-of

denotes an element which provides a list of assertions that must be all satisfied, if any of the assertions proves to be false then the test fails.

all-of

Negates an assertion: this assertion is satisfied if the contained assertion fails, and vice versa. Particularly useful with assert-serialization-matches.

abstractAssertion

Abstract superclass for the various kinds of assertion.

assert

The assert element contains an XPath expression whose effective boolean value must be true; usually the expression will use the variable $result which references the result of the expression.

For example, <assert>matches(string($result), '[0-9]{3}')</assert> asserts that the result of the test expression is a three-digit number.

assert-eq

The assert element contains an XPath expression (usually a simple string or numeric literal) which must be equal to the result of the test case under the rules of the XPath 'eq' operator.

For example, <assert-eq>12</assert-eq> asserts that the result of the test expression is an atomic value that compares equal to the integer 12 (which means it might be the double value 12.0 or the float value 12.0 or the untyped atomic value "12.0", for example).

assert-count

Asserts that the result must be a sequence containing a given number of items. The value of the element is an integer giving the expected length of the sequence.

assert-deep-eq

Asserts that the result must be a sequence of atomic values that is deep-equal to the supplied sequence under the rules of the deep-equal() function.

assert-permutation

Asserts that the result must be a sequence of atomic values that has some permutation (reordering) that is deep-equal to the supplied sequence under the rules of the deep-equal() function.

Note this implies that NaN is equal to NaN.

assert-xml

Asserts the result of the query by providing a serialization of the expression result using the default serialization parameters method="xml" indent="no" omit-xml-declaration="yes".

Previously called assert-serialization. Note that this assertion is not used to test serialization; it is used as a way of supplying the expected results of the query in the form of an XML document.

The assertion is true if the result of parsing and canonicalizing the XML given in the body of the assert-xml element is the same (byte-for-byte) as the result of canonicalizing the XML result of the query. As an alternative to canonicalizing, the results may be compared using the fn:deep-equal() function.

The value will not necessarily be a well-formed document (it may be a fragment). The comparison can be done by converting the string into a well-formed document by adding a wrapper element.

serialization-matches

Asserts the result of serializing the query matches a given regular expression.

The result of the query must be serialized using the serialization options specified within the query (if any).

The assertion is true if the output of the serializer (as a string) matches the regular expression, when compared using the matches() function with the specified flags. Note this is not an anchored match, unless anchors are included within the regular expression itself.

Note that the serializer output is treated as a string; we have no way of testing the encoding of serialized output when treated as an octet stream.

assert-serialization-error

Asserts that the query can be executed without error, but serializing the result produces a serialization error. The result of the query must be serialized using the serialization options specified within the query (if any).

assert-empty

Asserts that the result of the test is an empty sequence.

assert-type

Asserts that the result of the test matches the sequence type given as the value of the assert-type element.

assert-true

Asserts that the result of the test is the singleton boolean value true(). Note, the test expression must actually evaluate to true: this is not an assertion on the effective boolean value.

assert-true

Asserts that the result of the test is the singleton boolean value false(). Note, the test expression must actually evaluate to false: this is not an assertion on the effective boolean value.

assert-string-value

Asserts that the result of the test, after conversion to a string by applying the expression string-join(for $r in $result return string($r), " ") is equal to the string value of the assert-string-value element. Note that this test cannot be used if the result includes items that do not have a string value (elements with element-only content; function items) If the normalize-space attribute is present with the value true, then both the string value of the query result and the value of the assert-string-value element should be processed as if by the XPath normalize-space() function before the comparison.

error

Asserts that the test is expected to fail with a static or dynamic error condition. The "code" attribute gives the expected error code.

For the purpose of official test reporting, an implementation is considered to pass a test if the test expects and error and the implementation raises an error, regardless whether the error codes match. Implementors are advised, however, that raising the wrong error code often indicates a problem, so it is advisable to detect this situation. When reporting requirements are finalized, we will be asking implementors to indicate tests which passed but raised a different error, so that we can assess the extent to which implementations are interoperable at the level of error codes.

link

denotes an element which provides reference to documentation of the function.

document (as an attribute name)

denotes an attribute which provides a URI to be used as reference to specification.

code (as an attribute name)

denotes an attribute which in most cases provides a NCName to be used as an error code in the scope of a error element. The attribute gives the local name of the error code; the code is assumed to be in the standard error namespace.

The value "*" indicates that any error code is allowed.

The value may also be an EQName (Q{uri}local) to allow for user-defined error codes

file

This attribute provides a URI to be used as location of a resource within the test suite (for example, a source document, a query, a module, or a schema).

The URI will always be relative to the base URI of the XML document in which the attribute appears.

role

Describes how a source document is made available to the query.

The value "." indicates that the source document will be the context item for the query.

A value in the form $varname indicates that the source document will be made available as the value of the external variable $varname. This variable will not be declared in the query (this is to allow the mechanism to be used in XPath). The query will always be such that it is possible to add declare variable declarations at the start before compiling the query.

If the source document is to be made available to the query using the doc() function, the "source" element should have a "uri" attribute, and the "role" attribute should be absent.

The "role" attribute should be omitted if the source is part of a collection definition.

name

An attribute used to provide a string that uniquely names an object within some scope.

covers

An attribute used to cross-reference tests or test-sets to the changes in the specification that the tests are designed to cover.

The value is syntactically similar to an xs:IDREFS value, in that it contains a space-separated list of change identifiers; however it is not actually an xs:IDREFS value, because the identfiers are in a different XML document, specifically the identifiers of changes appearing in the changes.xml file.

covers-30

An attribute used to cross-reference tests or test-sets to the changes in the 3.0 specification that the tests are designed to cover.

The value is syntactically similar to an xs:IDREFS value, in that it contains a space-separated list of change identifiers; however it is not actually an xs:IDREFS value, because the identfiers are in a different XML document, specifically the identifiers of changes appearing in the changes.xml file.

creator

An attribute used to name the creator of a test-case.

Use of this attribute does not constitute a claim to intellectual property rights.

The recommended form is as a personal name (first name, last name). An institutional name may be used if policy requires it.

ref

denotes an attribute which contains a reference to an object defined elsewhere in the test catalog, for example a reference to a named environment.

Note, this is not typed as xs:IDREF because the reference might be to an object in a different XML document.

validation

indicates for a source document within an environment whether the source document is to be validated against the schema defined for that environment, and if so whether validation is to be strict or lax.

media-type

Describes the media type of a resource.

The value should conform to RFC 2046.

encoding

Describes the encoding of a resource.

The value should be that of a character set registered with the Internet Assigned Numbers Authority.

type

The type attribute of a dependency element indicates what type of dependency it is: the set of possible values is enumerated.

The most common type is spec, which indicates a dependency on specific versions of XPath or XQuery. In this case the corresponding value attribute is a space-separated list whose tokens are, for example, "XQ10" indicating XQuery 1.0, "XQ10+" indicating XQuery 1.0 or later, "XQ30+" indication XQuery 3.0 or later, or "XP20+" indicating XPath 2.0 or later. The tokens in the list are alternatives; the test may be run if any of the dependencies is satisfied.

Similarly, if the type is xml-version, the corresponding value is a space-separated list whose tokens are "1.0" (XML 1.0), "1.1" (XML 1.1), "1.0:5+" (1.0, 5th edition or later), "1.0:4-" (1.0, fourth edition or earlier).

value

As an attribute of the dependency element, provides a string value to be used to indicate the dependency.

uri (as an attribute name)

This attribute provides a URI to be used as an abstract identifier of a resource within the test suite (for example, a source document, or a module). The URI is designed to be independent of the location of the resource.

The URI may be an absolute URI or a relative URI reference. If it is a relative URI reference, it is resolved relative to the base URI of the element in which it appears (in practice, that is, the base URI of the test-set catalog file).

For source documents, the URI can be used in a call to the doc() function to retrieve this source document (so the actual query does not need to know its location.

For modules, the URI defines the module URI and is again independent of location.

For schemas, the URI defines the target namespace URI.

by (as an attribute name)

The name of the person who created or modified a test-case or source document, schema etc.

on (as an attribute name)

The date of an event such as the creation or modification of a test-case.

change (as an attribute name)

Textual explanation of a change made to a test-case.