rust-lang/rust · error · FailedCheck

Actual snapshot value is different than expected

Error message

Actual snapshot value is different than expected

What it means

Raised as FailedCheck by check_snapshot() when the snapshot golden file exists and was loaded, but the actual generated output differs from the expected (and --bless was not passed, so it was not auto-updated). Before raising, the expected and actual values are printed to stderr to aid diagnosis. This is the canonical 'rustdoc output changed' failure.

Source

Thrown at src/etc/htmldocck.py:385

    if (
        not expected_str
        or (
            not normalize_to_text
            and not compare_tree(make_xml(actual_str), make_xml(expected_str), stderr)
        )
        or (normalize_to_text and actual_str != expected_str)
    ):
        if bless:
            with open(snapshot_path, "w") as snapshot_file:
                actual_str = actual_str.replace(channel, "{{channel}}")
                snapshot_file.write(actual_str)
        else:
            print("--- expected ---\n")
            print(expected_str)
            print("\n\n--- actual ---\n")
            print(actual_str)
            print()
            raise FailedCheck("Actual snapshot value is different than expected")


# Adapted from https://github.com/formencode/formencode/blob/3a1ba9de2fdd494dd945510a4568a3afeddb0b2e/formencode/doctest_xml_compare.py#L72-L120
def compare_tree(x1, x2, reporter=None):
    if x1.tag != x2.tag:
        if reporter:
            reporter("Tags do not match: %s and %s" % (x1.tag, x2.tag))
        return False
    for name, value in x1.attrib.items():
        if x2.attrib.get(name) != value:
            if reporter:
                reporter(
                    "Attributes do not match: %s=%r, %s=%r"
                    % (name, value, name, x2.attrib.get(name))
                )
            return False
    for name in x2.attrib:
        if name not in x1.attrib:

View on GitHub (pinned to 7088e4b63a)

Solutions

1. Read the printed --- expected --- / --- actual --- diff to understand the delta.
2. If the new output is correct, re-bless: `htmldocckck.py <docdir> <template.rs> --bless` and commit the updated golden.
3. If the change is unintended, fix the rustdoc regression that produced it, then re-run.

Example fix

// before
$ ./htmldocck.py build/doc tests/ui/mytest.rs
# FailedCheck: Actual snapshot value is different than expected

// after - review the diff, then bless if intentional
$ ./htmldocck.py build/doc tests/ui/mytest.rs --bless
$ git diff tests/ui/mytest.my_snapshot.html   # review
$ git add tests/ui/mytest.my_snapshot.html

null

null

from srcetc_htmldocck import FailedCheck
try:
    check_snapshot(snapshot_name, subtree, normalize_to_text)
except FailedCheck as e:
    if "Actual snapshot value is different" in str(e):
        logging.error("snapshot drifted; review diff and re-bless if intentional")
    raise

When it happens

Trigger: A snapshot directive's subtree (either as serialized XML or flattened text, depending on whether the XPath ended in /text()) does not equal the stored golden. Reached at htmldocck.py:385 in the non-bless branch.

Common situations: A rustdoc change altered rendering (whitespace, attribute order, class names, wrapper elements); a dependency or theme change affected output; the {{channel}} placeholder substitution diverged; the test crate's items changed.

Related errors

• No saved snapshot value
• XPATH did not match
• Expected 1 match, but found {}
• line {}: {}
• Non-absolute XPath is not supported due to implementation is

AI-assisted analysis of rust-lang/rust@7088e4b63a (2026-08-10). Data as JSON: /api/errors/9bea7162f4be68b1. Report an issue: GitHub.