3.9 KiB
The rustdoc test suite
This page is specifically about the test suite named rustdoc.
For other test suites used for testing rustdoc, see Rustdoc tests.
The rustdoc test suite is specifically used to test the HTML output of rustdoc.
This is achieved by means of htmldocck.py, a custom checker script that leverages XPath.
Directives
Directives to htmldocck are similar to those given to compiletest in that they take the form of //@ comments.
In addition to the directives listed here,
rustdoc tests also support most
compiletest directives.
All PATHs in directives are relative to the the rustdoc output directory (build/TARGET/test/rustdoc/TESTNAME),
so it is conventional to use a #![crate_name = "foo"] attribute to avoid
having to write a long crate name multiple times.
To avoid repetion, - can be used in any PATH argument to re-use the previous PATH argument.
All arguments take the form of quoted strings
(both single and double quotes are supported),
with the exception of COUNT and the special - form of PATH.
Directives are assertions that place constraints on the generated HTML.
All directives (except files) can be negated by putting a ! in front of their name.
Similar to shell commands,
directives can extend across multiple lines if their last char is \.
In this case, the start of the next line should be //, with no @.
For example, //@ !has 'foo/struct.Bar.html' checks that crate foo does not have a page for a struct named Bar in the crate root.
has
Usage 1: //@ has PATH
Usage 2: //@ has PATH XPATH PATTERN
In the first form, has checks that a given file exists.
In the second form, has is an alias for matches,
except PATTERN is a whitespace-normalized1 string instead of a regex.
matches
Usage: //@ matches PATH XPATH PATTERN
Checks that the text of each element selected by XPATH in PATH matches the python-flavored regex PATTERN.
matchesraw
Usage: //@ matchesraw PATH PATTERN
Checks that the contents of the file PATH matches the regex PATTERN.
hasraw
Usage: //@ hasraw PATH PATTERN
Same as matchesraw, except PATTERN is a whitespace-normalized1 string instead of a regex.
count
Usage: //@ count PATH XPATH COUNT
Checks that there are exactly COUNT matches for XPATH within the file PATH.
snapshot
Usage: //@ snapshot NAME PATH XPATH
Creates a snapshot test named NAME.
A snapshot test captures a subtree of the DOM, at the location
determined by the XPath, and compares it to a pre-recorded value
in a file. The file's name is the test's name with the .rs extension
replaced with .NAME.html, where NAME is the snapshot's name.
htmldocck supports the --bless option to accept the current subtree
as expected, saving it to the file determined by the snapshot's name.
compiletest's --bless flag is forwarded to htmldocck.
has-dir
Usage: //@ has-dir PATH
Checks for the existance of directory PATH.
files
Usage: //@ files PATH ENTRIES
Checks that the directory PATH contains exactly ENTRIES.
ENTRIES is a python list of strings inside a quoted string,
as if it were to be parsed by eval.
(note that the list is actually parsed by shlex.split,
so it cannot contain arbitrary python expressions).
Example: //@ files "foo/bar" '["index.html", "sidebar-items.js"]'
Limitations
htmldocck.py uses the xpath implementation from the standard library.
This leads to several limitations:
- All
XPATHarguments must start with//due to a flaw in the implemention. - Many XPath features (functions, axies, etc.) are not supported.
- Only well-formed HTML can be parsed (hopefully rustdoc doesn't output mismatched tags).
-
Whitespace normalization means that all spans of consecutive whitespace are replaced with a single space. The files themselves are also whitespace-normalized. ↩︎