7 — Validating & comparing

The previous chapters dealt with one file at a time. This one answers the questions that concern the whole of your work:

• is this document conformant to its schema?
• is my entire folder still sound, or have I broken something?
• is this output identical to yesterday's?
• do my transformations still do what they are supposed to do?

Four tools answer: validation against a schema, batch validation, structural comparison and XSpec tests. All of them work offline.

7.1 Validating the active file

The Validate active file button on the toolbar checks the current tab on demand: well-formedness of the XML, compilation of a stylesheet, conformity to the associated schema.

It is independent of the Live validation setting: even with detection switched off, it answers. If the file is sound, a confirmation tells you so — « File "…" contains no syntax errors. »

Validation as you type, wavy underlines and associating a schema are dealt with in the chapter Editing §2.3 and §2.5.

7.2 Validating against an XSD schema or a DTD

The Validate an XML against a schema (XSD or DTD) button drops down a menu of three entries. The first two validate; the third, Associate a schema, merely links (chapter Editing §2.3).

The dialogue

XSD opens XSD Validation — Validate an XML file against an XSD schema — with two lists:

DTD opens the twin dialogue, DTD Validation, with the DTD: field.

Both lists are filled from the open workspace. If there is nothing to offer, the application says so rather than opening an empty dialogue: No XML file found in workspace, No XSD schema found in workspace, No DTD found in workspace.

What you see

The button greys out for the duration of the check — one at a time — and the console traces the whole operation, prefixed [XSD] or [DTD]:

[XSD] --- Starting XSD validation ---
[XSD] XML : C:\...\data.xml
[XSD] XSD : C:\...\catalogue.xsd
[XSD] ✓ "data.xml" is valid against "catalogue.xsd"

On failure, the console announces the number — ✗ Validation failed: 3 problem(s) found —, the status message sums up — XSD validation failed: 3 problem(s) — and the errors are placed as wavy underlines in the document, at the exact line and column. Every error is reported, not just the first.

To validate is to associate

A validation started from XSD or DTD records the link between the two files. The console confirms it:

[XSD] Association saved: data.xml -> catalogue.xsd

From that moment on, the document is validated live against that schema and completion is driven by it, with no other gesture from you. It is the quickest shortcut for equipping a document.

7.3 Validating a whole folder

Validating file by file does not tell you whether your project is sound. Batch validation sweeps a complete tree in one pass.

• Right-click a folder in the explorer → Validate folder;
• right-click the empty area of the explorer → Validate workspace.

The Problems tab of the bottom panel comes to the front. Before any use it shows Right-click a folder in the explorer to validate it.

What is checked

The sweep is recursive and treats each type according to its nature:

During and after

Progress is shown continuously — Validating… 12/57 — and the Cancel button interrupts at any moment: the tree stays frozen on what has already been seen, and the status becomes Validation cancelled.

The summary takes one of these forms:

The tree lists only the files with errors — a sound folder gives an empty tree, not a list of ticks. A single click on a problem opens the file and highlights the faulty line.

The batch reads the disk

That is the fundamental difference from validation as you type:

Batch validation reflects the state of the disk at the moment you start it. Your unsaved changes are not in it.

It does not let you fool yourself, though: a file whose tab is open and modified carries the unsaved badge. The result shown then does not match what you see in the editor — save and run it again.

7.4 Resolving schemas offline — XML catalogues

Some documents will not validate on a machine with no network, not because they are faulty, but because they designate their schemas by identifiers rather than by paths: an xsi:schemaLocation pointing at a URL, a DOCTYPE … PUBLIC, an xsl:include by logical URL.

An XML catalogue (OASIS 1.1) is the file that links these identifiers to your local files.

Declaring a catalogue

Two entries:

• Settings → XML Catalogs… opens the XML Catalogs (OASIS) dialogue;
• right-click an .xml file in the explorer → Use as XML catalog.

The dialogue presents the Catalogs (order = priority) list:

If your workspace holds a catalog.xml at its root, it is detected automatically and appears ticked, marked catalog.xml auto-detected (not persisted). It is already acting. As soon as you touch it — untick, remove, add a second catalogue — your choice is recorded and survives a restart.

What it unblocks

Once a catalogue is active, resolution applies everywhere, not only to validation:

Navigation and the Hierarchy view follow too: F12 on a template declared in a module included by logical URL takes you there.

The trace and the safeguard

Catalogue events go to the console, prefixed [Catalog]:

[Catalog] catalog.xml auto-detected at workspace root: C:\...\catalog.xml (not persisted)
[Catalog] 2 active catalog(s) (generation 3)

Two messages deserve attention:

• [Catalog] Non-local target ignored (offline mode): http://… — a catalogue rewrote an identifier towards a network address. It is never followed. Debug XML Tool does not leave your machine, even if a catalogue asks it to;
• [Catalog] Invalid catalog, ignored: … — … — a malformed catalogue is discarded on its own; the others stay active.

With no catalogue declared, nothing changes. Schema resolution stays exactly that of the previous chapters. Catalogues add a step only if you configure one.

Catalogues are recorded per workspace: two projects each have their own.

7.5 Comparing two files

Has my output changed? And if so, where?

Two entries:

• the Compare two files (structural XML diff) button on the toolbar, which asks in turn for Compare — first file then Compare — second file;
• right-click a file in the explorer → Compare with… — the first is already designated, only the second is asked of you.

What opens

An editor tab named source.xml ↔ reference.xml shows the two files side by side, read-only, with differences highlighted and marked in the gutter.

In parallel, the Comparison tab of the bottom panel comes to the front and lists the differences one by one:

Double-click a row: the difference is revealed in the right pane of the comparison tab.

The panel status sums up:

The verdict also goes to the console: Diff source.xml: 2 structural difference(s).

Structural, not line by line

This is what sets this tool apart from an ordinary diff, and it is the point to remember:

Two documents differing only in their indentation, the order of their attributes, their comments or their namespace prefixes are declared identical.

Reformatting an output therefore produces no noise. You only see what really changes: an element, an attribute, a text.

If one of the files is not XML, or is malformed, the comparison falls back on a text comparison and tells you so explicitly — it does not claim to have done better.

7.6 Comparing an output with its reference

The most useful case for comparison is the non-regression test: freeze a correct output, then check after each change that the new one is identical to it.

It is built into the transformation scenarios (chapter Transforming & exporting §3.7): fill in the Reference output: field, then use the Run and compare button. The transformation is run again and its result is compared with the reference, with the same structural engine as in §7.5.

The verdict appears in the console:

7.7 Running XSpec tests

XSpec is the reference unit-testing framework for XSLT. Debug XML Tool runs it directly, with no installation and no network: the engine is embedded.

Running the tests

Right-click an .xspec file in the explorer → Run XSpec tests. The XSpec tab of the bottom panel comes to the front. Before any use, it shows Right-click a .xspec file to run its tests.

The badge gives the count: 2 ✔ / 1 ✘ / 1 ⏸ — passed, failed, skipped.

The tree presents the scenarios, each expandable into tests, with the icon of its status. Failing scenarios are expanded from the start; the others stay folded. So you see first what is wrong.

A single click on a scenario or a test opens the .xspec and highlights the line of its label — you land on the declaration of the test, not on a report.

Understanding a failure

Select a failing test: a detail area appears below the tree, in two columns, Expected and Actual.

When the difference is not readable by eye, the Compare expected/actual button opens the two results in the structural comparison of §7.5 — same columns, same navigation.

The Re-run button replays the campaign without going back through the explorer.

Creating a test file

Right-click an .xsl or an .xslt → Generate XSpec skeleton. A name.xspec file is created next to the stylesheet and opened immediately; the console confirms it — XSpec skeleton created: …. All you have to do is fill in the scenarios.

A malformed .xspec breaks nothing: the panel shows XSpec error: … and stays usable for the next run.

The tests do not interfere with the debugger. They run on a separate engine: the state badge stays IDLE, your breakpoints are not reached, and a debugging session in progress is not disturbed.

7.8 Limits worth knowing

• XSD validation follows the W3C XML Schema 1.0 standard.
• Batch validation reflects the disk, never your buffers — the tabs concerned are flagged with the unsaved badge.
• xsl:include modules are validated in isolation by the batch: a module that only makes sense when imported into a main stylesheet may wrongly appear there as an error.
• The batch ignores files larger than 2 MB — they are counted in the summary — and caps the display at 10,000 problems (— display truncated). Its results are not kept from one session to the next.
• The comparison treats element order as significant: two documents holding the same elements in a different order are different.
• Beyond 10 MB, the comparison falls back on text mode, and the display is capped at 5,000 differences.
• No folder comparison, no merge: the comparison shows, it does not reconcile.
• Catalogues only resolve towards local files. Any target rewritten to a network address is ignored and traced — that is the price of working 100 % offline.
• An XSpec scenario cannot yet be debugged step by step: the tests run, but breakpoints do not apply to them.

What next

• Reference — every shortcut, button, menu and gesture, in tables.
• Analysing — profiler, template coverage, back-mapping.
• Transforming & exporting — scenarios and reference outputs.