Which tests are worth writing?
A project does not need hundreds of tests on day one. Start with a function that has caused trouble before, or a template that must keep working. Before writing the test, ask a straightforward question: how will we know that the result is right?
For a conversion, that might mean preserving all the text, keeping cross-references intact or retaining the order of table cells. Tests are useful both while developing new code and when maintaining existing stylesheets. Those were already the starting points of our XSpec training.
Valid XML is not necessarily the right output
A schema can check whether a document has a permitted structure. It does not automatically tell us whether a transformation handled the content correctly. Consider this paragraph:
<article>
<title>Publishing with XML</title>
<p>Read the <em>important</em> instructions.</p>
</article>A stylesheet could remove the em element and still produce valid XML. The emphasis would nevertheless be missing. An XSpec test can check that exact point and require the markup to remain. For a plain-text export, removing it might be intentional. The expected result depends on what the processing is meant to achieve.
Different jobs suggest different places to test:
| What do we test? | What do we want to know? | Example in this package |
|---|---|---|
| Function | Does it return the right value? | Hexadecimal conversion or a column name |
| Template | Is this XML fragment transformed correctly? | A paragraph initial or citation |
| Module | Are the selection and order correct? | Filtering books with XQuery |
| Schematron rule | Does it report the intended error? | An empty title or missing reference target |
| XProc step | Do the input and output match the requirement? | Wrapping a document in an element |
Small tests make bugs easier to locate. A test of a complete export can reveal whether the parts work together. Both are useful; XSpec does not require a particular hierarchy.
Typical publishing tasks
When migrating between XML formats, identifiers, references, tables and content order make useful test cases. In a shared XSLT library, start with numbering, file-name generation or metadata functions. For customer-specific changes, tests help prevent a new rule for one customer from altering another customer's output.
An existing bug is often the easiest starting point. Reduce the source document to the fragment that triggers it. Save the intended output and write the test. Then repair the stylesheet. If the same bug returns later, the test catches it. That is the practical purpose of a regression test.
Whole documents or selected properties?
For a short paragraph, saving the complete expected XML is often simplest. For a large document, an XPath check may be more useful: are all the identifiers still present? Is there exactly one main heading? Do references still point to the intended targets?
A test should cover what matters without failing on every irrelevant formatting change. But checking only that some output exists is not enough when a particular structure is required.
Add a few difficult inputs alongside the normal case: an empty paragraph, a missing attribute, another namespace or the transition from Z to AA. These often find more bugs than many almost identical sample documents.