Recursive AI

Diff accessibility trees in C#

onehtml is a free, open-source HTML library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Compare accessibility roles, names and states after an HTML edit, without a browser.

Terminal
dotnet add package RecursiveAI.OneHtml.Accessibility

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Editing;
using RecursiveAI.OneHtml.Accessibility;
 
var doc = Document.Parse(
    "<button>Save</button>");
var styles = DocumentStyles.Create(doc);
var before = AccessibilityTree.Build(
    doc, styles);
var edit = doc.Apply([Edit.SetAttribute(
    doc.Root.QuerySelector("button"),
    "aria-label", "Send")]);
if (!edit.Succeeded)
    throw new Exception(edit.Failure);
var after = before.Update(
    edit, styles.Restyle(edit));
var diff = before.Diff(after, edit.Changes);
Console.WriteLine(
    $"Changed: {diff.Changed.Count}");
Text
Changed: 1

Unzip the example, then dotnet run.

The full program

The snippet at the top renames a button. The full program also disables it, then prints each changed property. Both HTML inputs are inline; no input files are needed.

C#
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Css;
using RecursiveAI.OneHtml.Editing;
using RecursiveAI.OneHtml.Accessibility;
 
var doc = Document.Parse("<button aria-label='Save'>Go</button>");
var styles = DocumentStyles.Create(doc);
var before = AccessibilityTree.Build(doc, styles);
var button = doc.Root.QuerySelector("button");
var edit = doc.Apply([
    Edit.SetAttribute(button, "aria-label", "Send"),
    Edit.SetAttribute(button, "disabled", "")]);
if (!edit.Succeeded)
    throw new InvalidOperationException(edit.Failure);
var after = before.Update(edit, styles.Restyle(edit));
var diff = before.Diff(after, edit.Changes);
foreach (var node in diff.Changed)
    foreach (var change in node.Properties)
        Console.WriteLine($"{change.Property}: {change.OldValue} -> {change.NewValue}");
Console.WriteLine($"Added: {diff.Added.Count}; removed: {diff.Removed.Count}");

dotnet run prints:

Text
name: Save -> Send
focusable: true -> false
tabbable: true -> false
disabled:  -> true
Added: 0; removed: 0

An edit failure throws with its failure message before any tree update.

Variations

Report removed nodes

Append this to the full program. It removes the button from the edited document and compares the result with after, so the button and its text node disappear from that snapshot.

C#
var editedDoc = edit.Document!;
var editedStyles = styles.Restyle(edit).Styles;
var editedButton = editedDoc.Root.QuerySelector("button");
var removal = editedDoc.Apply([Edit.Remove(editedButton)]);
if (!removal.Succeeded)
    throw new InvalidOperationException(removal.Failure);
var withoutButton = after.Update(
    removal, editedStyles.Restyle(removal));
var removed = after.Diff(withoutButton, removal.Changes);
Console.WriteLine($"Removed: {removed.Removed.Count}");
Text
Removed: 2

The short answer

Use AccessibilityTree.Diff to compare accessibility snapshots in C#. Build a tree from a parsed document and its styles, apply an edit, update the styles and tree, then pass the edit’s Changes to Diff. The result separates added nodes, removed nodes and property changes on matched nodes.

This is a semantic comparison, not a text-file diff. Changing aria-label can change a button’s accessible name without changing its visible text. Disabling the same button changes its disabled state and whether it can receive focus. The full program shows both effects while preserving the identity of the button across the edit.

How do you diff accessibility trees in C#?

Keep the earlier tree and the edit result together. before.Diff(after, edit.Changes) uses the change set to map DOM nodes from the earlier document to the edited snapshot. The mapping is what lets the result say “this button’s name changed” rather than treating it as an unrelated deletion and insertion.

For two style contexts of the same document, matching uses DOM identity and no edit mapping is needed. Across an edit, supply the change set. Two independently parsed HTML strings do not provide that edit identity, even if their markup looks similar. For a regression workflow, express the change through the editing API and retain its result rather than parsing replacement HTML into a separate document.

Each entry in Changed provides the earlier node, the later node and a fixed-order list of properties. A property absent on one side has a null value there. In the output above, the blank before true for disabled means no earlier value was present. It is not the text false. The tree documentation defines the matching and property rules.

How is an accessibility tree different from the DOM?

The DOM represents the parsed HTML. The accessibility tree derives roles, names, descriptions, states and relationships from that HTML and its styles. A visible button’s text and its accessible name can differ, as the sample’s “Go” text and aria-label demonstrate. A structural markup edit may also leave every reported accessibility property unchanged.

Chrome’s explanation of the accessibility tree distinguishes its internal tree from the filtered tree displayed in DevTools. onehtml also keeps ignored nodes in its tree. Do not assume every added or removed node is an exposed control: inspect its role and ignored status when deciding whether a change matters.

What does an accessibility tree diff example report?

The first example reports one matched node with changed properties. The removal variation reports two removed nodes: the button and its text child. Added and Removed enumerate every unmatched node of a subtree, not just its root. Avoid interpreting their counts as numbers of user-facing controls.

The diff covers roles, names, descriptions, ignored and hidden status, focusability, tabbability, relations and individual states. It does not turn those differences into WCAG pass or fail decisions. A renamed button might be a correction or a regression; review it against the intended interaction.

These examples derive snapshots from local HTML and styles. They do not execute page scripts or observe a live interaction. If your change depends on browser layout, use the documented rendered-facts path to build the snapshots with that information. An empty diff means no reported differences in these snapshots, not that every aspect of the page is accessible.

All onehtml recipes