" in str(visitor.root.label)
+
+ def test_nested_tree(self) -> None:
+ child = BlankNode()
+ parent = ListNode([child])
+
+ visitor = _StrVisitor()
+ parent.visit(visitor)
+
+ assert visitor.root is not None
+
+
+class TestDocument:
+ def test_init_with_root(self) -> None:
+ root = BlankNode()
+ doc = Document(root)
+ assert doc.root is root
+
+ def test_extension_returns_none_when_no_output_nodes(self) -> None:
+ root = BlankNode()
+ doc = Document(root)
+ assert doc.extension() is None
+
+ def test_extension_returns_extension_from_output_node(self) -> None:
+ from io import TextIOBase
+
+ from docc.context import Context
+
+ class TestOutputNode(OutputNode):
+ @property
+ def children(self):
+ return ()
+
+ def replace_child(self, old: Node, new: Node) -> None:
+ pass
+
+ @property
+ def extension(self) -> str:
+ return ".test"
+
+ def output(
+ self, context: Context, destination: TextIOBase
+ ) -> None:
+ pass
+
+ root = TestOutputNode()
+ doc = Document(root)
+ assert doc.extension() == ".test"
+
+
+class TestExtensionVisitor:
+ def test_finds_extension(self) -> None:
+ from io import TextIOBase
+
+ from docc.context import Context
+
+ class TestOutputNode(OutputNode):
+ @property
+ def children(self):
+ return ()
+
+ def replace_child(self, old: Node, new: Node) -> None:
+ pass
+
+ @property
+ def extension(self) -> str:
+ return ".html"
+
+ def output(
+ self, context: Context, destination: TextIOBase
+ ) -> None:
+ pass
+
+ root = TestOutputNode()
+ visitor = _ExtensionVisitor()
+ root.visit(visitor)
+
+ assert visitor.extension == ".html"
+
+ def test_returns_none_when_no_output_nodes(self) -> None:
+ root = BlankNode()
+ visitor = _ExtensionVisitor()
+ root.visit(visitor)
+
+ assert visitor.extension is None
+
+ def test_conflicting_extensions_logs_warning(
+ self, caplog: pytest.LogCaptureFixture
+ ) -> None:
+ """
+ When two OutputNodes have different extensions, the visitor
+ logs a warning and keeps the first extension.
+ """
+ import logging
+ from io import TextIOBase
+
+ from docc.context import Context
+
+ class HtmlOutputNode(OutputNode):
+ @property
+ def children(self):
+ return ()
+
+ def replace_child(self, old: Node, new: Node) -> None:
+ pass
+
+ @property
+ def extension(self) -> str:
+ return ".html"
+
+ def output(
+ self, context: Context, destination: TextIOBase
+ ) -> None:
+ pass
+
+ class TxtOutputNode(OutputNode):
+ @property
+ def children(self):
+ return ()
+
+ def replace_child(self, old: Node, new: Node) -> None:
+ pass
+
+ @property
+ def extension(self) -> str:
+ return ".txt"
+
+ def output(
+ self, context: Context, destination: TextIOBase
+ ) -> None:
+ pass
+
+ root = ListNode([HtmlOutputNode(), TxtOutputNode()])
+ visitor = _ExtensionVisitor()
+
+ with caplog.at_level(logging.WARNING):
+ root.visit(visitor)
+
+ # The first extension is kept
+ assert visitor.extension == ".html"
+ # A warning was logged about the conflict
+ assert any("extension" in r.message for r in caplog.records)
+
+
+class ConditionalSkipVisitor(RecordingVisitor):
+ skip_after_first: bool
+
+ def __init__(self, skip_after_first: bool = False) -> None:
+ super().__init__()
+ self.skip_after_first = skip_after_first
+ self._first_seen = False
+
+ @override
+ def enter(self, node: Node) -> Visit:
+ self.events.append(("enter", id(node)))
+ if self.skip_after_first and not self._first_seen:
+ self._first_seen = True
+ return Visit.TraverseChildren
+ elif self.skip_after_first:
+ return Visit.SkipChildren
+ return Visit.TraverseChildren
+
+
+class TestVisitorEdgeCases:
+ def test_visit_empty_list_node(self) -> None:
+ node = ListNode([])
+ visitor = RecordingVisitor()
+ node.visit(visitor)
+
+ assert visitor.events == [
+ ("enter", id(node)),
+ ("exit", id(node)),
+ ]
+
+ def test_visit_deeply_nested(self) -> None:
+ node: Node = BlankNode()
+ for _ in range(10):
+ node = ListNode([node])
+
+ visitor = RecordingVisitor()
+ node.visit(visitor)
+
+ enter_count = sum(1 for e in visitor.events if e[0] == "enter")
+ assert enter_count == 11
+
+ def test_visit_wide_tree(self) -> None:
+ children: List[Node] = [BlankNode() for _ in range(100)]
+ node = ListNode(children)
+
+ visitor = RecordingVisitor()
+ node.visit(visitor)
+
+ enter_count = sum(
+ 1
+ for e in visitor.events
+ if e[0] == "enter" and e != ("enter", id(node))
+ )
+ assert enter_count == 100
+
+ def test_conditional_skip(self) -> None:
+ grandchild = BlankNode()
+ child = ListNode([grandchild])
+ parent = ListNode([child])
+
+ visitor = ConditionalSkipVisitor(skip_after_first=True)
+ parent.visit(visitor)
+
+ assert ("enter", id(grandchild)) not in visitor.events
+
+
+class ModifyingVisitor(Visitor):
+ def __init__(self, old: Node, new: Node) -> None:
+ self.old = old
+ self.new = new
+ self.stack: List[Node] = []
+
+ @override
+ def enter(self, node: Node) -> Visit:
+ self.stack.append(node)
+ return Visit.TraverseChildren
+
+ @override
+ def exit(self, node: Node) -> None:
+ self.stack.pop()
+ if node == self.old and self.stack:
+ self.stack[-1].replace_child(self.old, self.new)
+
+
+class SkipSpecificChildVisitor(Visitor):
+ """Visitor that returns SkipChildren for a specific child node."""
+
+ enter_calls: List[Node]
+ exit_calls: List[Node]
+ skip_target: Node
+
+ def __init__(self, skip_target: Node) -> None:
+ self.enter_calls = []
+ self.exit_calls = []
+ self.skip_target = skip_target
+
+ @override
+ def enter(self, node: Node) -> Visit:
+ self.enter_calls.append(node)
+ if node is self.skip_target:
+ return Visit.SkipChildren
+ return Visit.TraverseChildren
+
+ @override
+ def exit(self, node: Node) -> None:
+ self.exit_calls.append(node)
+
+
+def test_visit_skip_children_calls_exit() -> None:
+ grandchild = BlankNode()
+ skipped_child = ListNode([grandchild])
+ other_child = BlankNode()
+ parent = ListNode([skipped_child, other_child])
+
+ visitor = SkipSpecificChildVisitor(skip_target=skipped_child)
+ parent.visit(visitor)
+
+ # exit must be called for the child that returned SkipChildren
+ assert skipped_child in visitor.exit_calls
+
+ # The grandchild should NOT have been entered (children were skipped)
+ assert grandchild not in visitor.enter_calls
+
+ # Both the skipped child and the other child should have exit called
+ assert other_child in visitor.exit_calls
+ assert parent in visitor.exit_calls
+
+
+def test_visit_replace_during_exit() -> None:
+ old_child = BlankNode()
+ new_child = BlankNode()
+ parent = ListNode([old_child])
+
+ visitor = ModifyingVisitor(old_child, new_child)
+ parent.visit(visitor)
+
+ assert old_child not in parent.children
+ assert new_child in parent.children
diff --git a/tests/test_files.py b/tests/test_files.py
new file mode 100644
index 0000000..9ad7737
--- /dev/null
+++ b/tests/test_files.py
@@ -0,0 +1,227 @@
+# Copyright (C) 2026 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+from io import StringIO
+from pathlib import Path, PurePath
+from typing import Dict, Optional, Set
+
+import pytest
+
+from docc.context import Context
+from docc.document import BlankNode, Document
+from docc.plugins.files import (
+ FileNode,
+ FilesBuilder,
+ FilesDiscover,
+ FileSource,
+)
+from docc.settings import PluginSettings, Settings
+from docc.source import Source
+
+
+@pytest.fixture
+def plugin_settings(tmp_path: Path) -> PluginSettings:
+ settings = Settings(tmp_path, {"tool": {"docc": {}}})
+ return settings.for_plugin("docc.files.discover")
+
+
+class TestFileSource:
+ def test_init(self) -> None:
+ relative = PurePath("src/file.txt")
+ absolute = PurePath("/path/to/src/file.txt")
+ source = FileSource(relative, absolute)
+
+ assert source.relative_path == relative
+ assert source.absolute_path == absolute
+
+ def test_output_path_removes_suffix(self) -> None:
+ relative = PurePath("docs/readme.md")
+ absolute = PurePath("/path/docs/readme.md")
+ source = FileSource(relative, absolute)
+
+ assert source.output_path == PurePath("docs/readme")
+
+ def test_output_path_compound_extension(self) -> None:
+ relative = PurePath("static/chota.min.css")
+ absolute = PurePath("/path/static/chota.min.css")
+ source = FileSource(relative, absolute)
+
+ assert source.output_path == PurePath("static/chota.min")
+
+ def test_output_path_no_suffix(self) -> None:
+ relative = PurePath("docs/readme")
+ absolute = PurePath("/path/docs/readme")
+ source = FileSource(relative, absolute)
+
+ assert source.output_path == PurePath("docs/readme")
+
+
+class TestFileNode:
+ def test_init(self, tmp_path: Path) -> None:
+ file_path = tmp_path / "test.txt"
+ file_path.write_text("content")
+
+ node = FileNode(file_path)
+ assert node.path == file_path
+
+ def test_children_empty(self, tmp_path: Path) -> None:
+ file_path = tmp_path / "test.txt"
+ file_path.write_text("content")
+
+ node = FileNode(file_path)
+ assert node.children == ()
+
+ def test_replace_child_raises(self, tmp_path: Path) -> None:
+ file_path = tmp_path / "test.txt"
+ file_path.write_text("content")
+
+ node = FileNode(file_path)
+ with pytest.raises(TypeError):
+ node.replace_child(BlankNode(), BlankNode())
+
+ def test_extension(self, tmp_path: Path) -> None:
+ file_path = tmp_path / "test.txt"
+ file_path.write_text("content")
+
+ node = FileNode(file_path)
+ assert node.extension == ".txt"
+
+ def test_extension_multiple_suffixes(self, tmp_path: Path) -> None:
+ file_path = tmp_path / "chota.min.css"
+ file_path.write_text("content")
+
+ node = FileNode(file_path)
+ assert node.extension == ".css"
+
+ def test_output(self, tmp_path: Path) -> None:
+ file_path = tmp_path / "test.txt"
+ file_path.write_text("file content here")
+
+ node = FileNode(file_path)
+ context = Context({})
+ destination = StringIO()
+
+ node.output(context, destination)
+
+ assert destination.getvalue() == "file content here"
+
+
+class TestFilesBuilder:
+ def test_build_processes_file_sources(
+ self, tmp_path: Path, plugin_settings: PluginSettings
+ ) -> None:
+ file_path = tmp_path / "test.txt"
+ file_path.write_text("content")
+
+ source = FileSource(PurePath("test.txt"), file_path)
+ unprocessed: Set[Source] = {source}
+ processed: Dict[Source, Document] = {}
+
+ builder = FilesBuilder(plugin_settings)
+ builder.build(unprocessed, processed)
+
+ assert source in processed
+ assert len(processed) == 1
+ assert len(unprocessed) == 0
+ assert isinstance(processed[source].root, FileNode)
+
+ def test_build_ignores_non_file_sources(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ class OtherSource(Source):
+ @property
+ def relative_path(self) -> Optional[PurePath]:
+ return PurePath("other.py")
+
+ @property
+ def output_path(self) -> PurePath:
+ return PurePath("other.py")
+
+ source = OtherSource()
+ unprocessed: Set[Source] = {source}
+ processed: Dict[Source, Document] = {}
+
+ builder = FilesBuilder(plugin_settings)
+ builder.build(unprocessed, processed)
+
+ assert source in unprocessed
+ assert len(processed) == 0
+
+
+class TestFilesDiscover:
+ def test_init_no_files(self, tmp_path: Path) -> None:
+ settings = Settings(tmp_path, {"tool": {"docc": {}}})
+ plugin_settings = settings.for_plugin("docc.files.discover")
+
+ discover = FilesDiscover(plugin_settings)
+ assert discover.sources == []
+
+ def test_init_with_files(self, tmp_path: Path) -> None:
+ first_file = tmp_path / "file1.txt"
+ first_file.write_text("content1")
+ second_file = tmp_path / "file2.txt"
+ second_file.write_text("content2")
+
+ settings = Settings(
+ tmp_path,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.files.discover": {
+ "files": ["file1.txt", "file2.txt"]
+ }
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.files.discover")
+
+ discover = FilesDiscover(plugin_settings)
+ assert len(discover.sources) == 2
+
+ def test_discover_yields_sources(self, tmp_path: Path) -> None:
+ first_file = tmp_path / "file1.txt"
+ first_file.write_text("content")
+
+ settings = Settings(
+ tmp_path,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.files.discover": {"files": ["file1.txt"]}
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.files.discover")
+
+ discover = FilesDiscover(plugin_settings)
+ sources = list(discover.discover(frozenset()))
+
+ assert len(sources) == 1
+ assert isinstance(sources[0], FileSource)
+
+ def test_discover_empty_when_no_files(self, tmp_path: Path) -> None:
+ settings = Settings(tmp_path, {"tool": {"docc": {}}})
+ plugin_settings = settings.for_plugin("docc.files.discover")
+
+ discover = FilesDiscover(plugin_settings)
+ sources = list(discover.discover(frozenset()))
+
+ assert sources == []
diff --git a/tests/test_html_e2e.py b/tests/test_html_e2e.py
new file mode 100644
index 0000000..91be245
--- /dev/null
+++ b/tests/test_html_e2e.py
@@ -0,0 +1,482 @@
+# Copyright (C) 2026 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+"""
+End-to-end tests for the HTML rendering pipeline.
+
+These tests exercise the full docc pipeline path through HTML rendering:
+discover -> build -> context -> transform -> HTML render -> file output.
+"""
+
+from io import StringIO
+from pathlib import PurePath
+from typing import Optional
+
+from docc.context import Context
+from docc.document import BlankNode, Document, ListNode
+from docc.plugins.html import (
+ HTML,
+ HTMLRoot,
+ HTMLTag,
+ HTMLTransform,
+ TextNode,
+ blank_node,
+ html_tag,
+ list_node,
+ references_definition,
+ references_reference,
+ render_reference,
+ text_node,
+)
+from docc.plugins.references import (
+ Definition,
+ Index,
+ IndexTransform,
+ Reference,
+)
+from docc.settings import PluginSettings
+from docc.source import Source, StringSource
+
+
+class _MockSource(StringSource):
+ """A minimal Source implementation for testing."""
+
+ def __init__(
+ self,
+ output_path: Optional[PurePath] = None,
+ relative_path: Optional[PurePath] = None,
+ ) -> None:
+ if output_path is None:
+ output_path = PurePath("test.py")
+ if relative_path is None:
+ relative_path = output_path
+
+ super().__init__("", output_path, relative_path)
+
+
+class TestHTMLTransformProducesHTMLRoot:
+ """
+ Test that HTMLTransform replaces a document tree with an HTMLRoot.
+
+ This exercises the pipeline step where the document tree (containing
+ Definition, BlankNode, ListNode, etc.) is converted into an HTML tree
+ via HTMLVisitor and the entry-point-based renderer lookup.
+ """
+
+ def test_definition_with_blank_becomes_html_root(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ """
+ A document containing a Definition wrapping a BlankNode is
+ transformed into an HTMLRoot.
+
+ The Definition renderer (references_definition) internally creates
+ its own HTMLVisitor to render children, so this exercises the
+ nested visitor path through the entry point system.
+ """
+ source = _MockSource(PurePath("docs/module.py"))
+ index = Index()
+
+ definition = Definition(
+ identifier="my_module.MyClass", child=BlankNode()
+ )
+
+ document = Document(definition)
+ context = Context({Document: document, Source: source, Index: index})
+
+ # First apply IndexTransform to assign specifiers.
+ index_transform = IndexTransform(plugin_settings)
+ index_transform.transform(context)
+ assert definition.specifier == 0
+
+ # Then apply HTMLTransform.
+ html_transform = HTMLTransform(plugin_settings)
+ html_transform.transform(context)
+
+ assert isinstance(document.root, HTMLRoot)
+
+ def test_transform_skips_already_output_node(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ """
+ If the document root is already an OutputNode (e.g. HTMLRoot),
+ HTMLTransform leaves it unchanged.
+ """
+ context = Context({})
+ existing_root = HTMLRoot(context)
+ existing_root.append(HTMLTag("div"))
+ document = Document(existing_root)
+ context = Context({Document: document})
+
+ transform = HTMLTransform(plugin_settings)
+ transform.transform(context)
+
+ assert document.root is existing_root
+
+
+class TestHTMLRootOutputProducesValidHTML:
+ """
+ Test that HTMLRoot.output() renders a full HTML document string
+ containing the expected structural elements from the Jinja2 template.
+ """
+
+ def test_output_includes_static_css_links(self) -> None:
+ """The rendered HTML includes links to chota and docc CSS."""
+ source = _MockSource(PurePath("docs/page.py"))
+ context = Context({Source: source})
+ root = HTMLRoot(context)
+ root.append(HTMLTag("p"))
+
+ buffer = StringIO()
+ root.output(context, buffer)
+ output = buffer.getvalue()
+
+ assert "chota.min.css" in output
+ assert "docc.css" in output
+
+ def test_output_with_extra_css(self) -> None:
+ """Extra CSS files configured via HTML context appear in output."""
+ source = _MockSource(PurePath("index.py"))
+ html_config = HTML(extra_css=["custom.css"], breadcrumbs=True)
+ context = Context({Source: source, HTML: html_config})
+ root = HTMLRoot(context)
+ root.append(HTMLTag("p"))
+
+ buffer = StringIO()
+ root.output(context, buffer)
+ output = buffer.getvalue()
+
+ assert "custom.css" in output
+
+ def test_output_breadcrumbs_for_nested_path(self) -> None:
+ """Breadcrumbs are rendered for documents in nested directories."""
+ source = _MockSource(PurePath("a/b/c/page.py"))
+ context = Context({Source: source})
+ root = HTMLRoot(context)
+ root.append(HTMLTag("section"))
+
+ buffer = StringIO()
+ root.output(context, buffer)
+ output = buffer.getvalue()
+
+ assert "breadcrumbs" in output
+ assert "page.py" in output
+
+ def test_output_no_breadcrumbs_when_disabled(self) -> None:
+ """Breadcrumbs section is absent when breadcrumbs=False."""
+ source = _MockSource(PurePath("a/b/page.py"))
+ html_config = HTML(extra_css=[], breadcrumbs=False)
+ context = Context({Source: source, HTML: html_config})
+ root = HTMLRoot(context)
+ root.append(HTMLTag("div"))
+
+ buffer = StringIO()
+ root.output(context, buffer)
+ output = buffer.getvalue()
+
+ assert "breadcrumbs" not in output
+
+ def test_output_nested_html_tags_produce_markup(self) -> None:
+ """Nested HTMLTag structures are correctly serialized."""
+ source = _MockSource(PurePath("page.py"))
+ context = Context({Source: source})
+ root = HTMLRoot(context)
+
+ section = HTMLTag("section", {"id": "main"})
+ heading = HTMLTag("h1")
+ heading.append(TextNode("Title"))
+ section.append(heading)
+ paragraph = HTMLTag("p")
+ paragraph.append(TextNode("Body text"))
+ section.append(paragraph)
+ root.append(section)
+
+ buffer = StringIO()
+ root.output(context, buffer)
+ output = buffer.getvalue()
+
+ assert "" in output
+ assert "Title" in output
+ assert "" in output
+ assert "Body text" in output
+
+
+class TestDefinitionRendersWithId:
+ """
+ Test that rendering a Definition node produces HTML with an id
+ attribute matching the definition's identifier and specifier.
+ """
+
+ def test_definition_blank_child_gets_id(self) -> None:
+ """
+ Calling references_definition directly with a Definition whose
+ child is a BlankNode produces a span with the correct id.
+ """
+ source = _MockSource(PurePath("docs/module.py"))
+ index = Index()
+ location = index.define(source, "my_func")
+
+ definition = Definition(
+ identifier="my_func",
+ child=BlankNode(),
+ specifier=location.specifier,
+ )
+
+ context = Context({Source: source, Index: index})
+ parent = HTMLRoot(context)
+
+ result = references_definition(context, parent, definition)
+ # references_definition appends to parent and returns None.
+ assert result is None
+
+ children = list(parent.children)
+ assert len(children) >= 1
+
+ first = children[0]
+ assert isinstance(first, HTMLTag)
+ assert first.tag_name == "span"
+ assert first.attributes.get("id") == "my_func:0"
+
+ def test_definition_with_list_child_gets_id(self) -> None:
+ """
+ A Definition wrapping a ListNode containing an HTMLTag gets
+ the id applied to the first rendered child element.
+ """
+ source = _MockSource(PurePath("docs/module.py"))
+ index = Index()
+ location = index.define(source, "MyClass")
+
+ # The child is an HTMLTag so that after HTMLVisitor renders
+ # the ListNode's children, the first child is already an HTMLTag.
+ inner_tag = HTMLTag("div", {"class": "class-def"})
+ inner_tag.append(TextNode("MyClass"))
+ child_list = ListNode([inner_tag])
+
+ definition = Definition(
+ identifier="MyClass",
+ child=child_list,
+ specifier=location.specifier,
+ )
+
+ context = Context({Source: source, Index: index})
+ parent = HTMLRoot(context)
+
+ references_definition(context, parent, definition)
+
+ children = list(parent.children)
+ assert len(children) >= 1
+
+ first = children[0]
+ assert isinstance(first, HTMLTag)
+ assert first.attributes.get("id") == "MyClass:0"
+
+ def test_definition_text_child_wrapped_in_span(self) -> None:
+ """
+ When the first rendered child is a TextNode, it gets wrapped
+ in a and the id is set on the span.
+ """
+ source = _MockSource(PurePath("docs/module.py"))
+ index = Index()
+ location = index.define(source, "some_var")
+
+ text = TextNode("some_var")
+ inner_tag = HTMLTag("p")
+ inner_tag.append(text)
+ child_list = ListNode([inner_tag])
+
+ definition = Definition(
+ identifier="some_var",
+ child=child_list,
+ specifier=location.specifier,
+ )
+
+ context = Context({Source: source, Index: index})
+ parent = HTMLRoot(context)
+
+ references_definition(context, parent, definition)
+
+ children = list(parent.children)
+ assert len(children) >= 1
+
+ first = children[0]
+ assert isinstance(first, HTMLTag)
+ assert first.attributes.get("id") == "some_var:0"
+
+
+class TestReferenceRendersAsLink:
+ """
+ Test that rendering a Reference produces an tag linking to the
+ definition's location.
+ """
+
+ def test_same_file_reference_has_fragment_only(self) -> None:
+ """
+ When the reference and definition are in the same source file,
+ the href is just a fragment (no file path component).
+ """
+ source = _MockSource(PurePath("docs/module.py"))
+
+ index = Index()
+ index.define(source, "local_func")
+
+ context = Context({Source: source, Index: index})
+ ref = Reference(identifier="local_func")
+
+ anchor = render_reference(context, ref)
+
+ assert isinstance(anchor, HTMLTag)
+ href = anchor.attributes.get("href", "")
+ assert href is not None
+ assert "local_func:0" in href
+
+ def test_references_reference_appends_anchor(self) -> None:
+ """
+ The references_reference render function appends an anchor to the
+ parent and returns it for child traversal when a child is present.
+ """
+ source = _MockSource(PurePath("docs/page.py"))
+ def_source = _MockSource(PurePath("docs/target.py"))
+
+ index = Index()
+ index.define(def_source, "func")
+
+ context = Context({Source: source, Index: index})
+ parent = HTMLRoot(context)
+
+ child_node = HTMLTag("code")
+ child_node.append(TextNode("func"))
+ ref = Reference(identifier="func", child=child_node)
+
+ result = references_reference(context, parent, ref)
+
+ # When the reference has a child, the anchor is returned so
+ # the visitor can traverse into it.
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "a"
+ assert result in parent.children
+
+ def test_references_reference_no_child_appends_text(self) -> None:
+ """
+ When a Reference has no meaningful child (BlankNode), the anchor
+ gets a TextNode with the identifier and returns None.
+ """
+ source = _MockSource(PurePath("docs/page.py"))
+ def_source = _MockSource(PurePath("docs/target.py"))
+
+ index = Index()
+ index.define(def_source, "some_id")
+
+ context = Context({Source: source, Index: index})
+ parent = HTMLRoot(context)
+
+ ref = Reference(identifier="some_id")
+
+ result = references_reference(context, parent, ref)
+
+ assert result is None
+ children = list(parent.children)
+ assert len(children) == 1
+ anchor = children[0]
+ assert isinstance(anchor, HTMLTag)
+ assert anchor.tag_name == "a"
+
+ anchor_children = list(anchor.children)
+ assert len(anchor_children) == 1
+ text_child = anchor_children[0]
+ assert isinstance(text_child, TextNode)
+ assert text_child._value == "some_id"
+
+
+class TestFullPipelineHTMLOutput:
+ """
+ Integration test: build a document tree, apply transforms, render
+ to an HTML string, and verify the output contains all expected
+ structural and content elements.
+ """
+
+ def test_definition_to_html_output(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ """
+ Full pipeline: Definition with BlankNode -> IndexTransform ->
+ HTMLTransform -> HTMLRoot.output() -> HTML string.
+ """
+ source = _MockSource(PurePath("docs/example.py"))
+ index = Index()
+
+ definition = Definition(
+ identifier="example.hello",
+ child=BlankNode(),
+ )
+ tree = ListNode([definition])
+ document = Document(tree)
+
+ context = Context({Document: document, Source: source, Index: index})
+
+ # Step 1: IndexTransform assigns specifiers.
+ index_transform = IndexTransform(plugin_settings)
+ index_transform.transform(context)
+ assert definition.specifier == 0
+
+ # Step 2: HTMLTransform converts the tree to HTML.
+ html_transform = HTMLTransform(plugin_settings)
+ html_transform.transform(context)
+ root = document.root
+ assert isinstance(root, HTMLRoot)
+
+ # Step 3: Output the HTML to a string.
+ buffer = StringIO()
+ root.output(context, buffer)
+ output = buffer.getvalue()
+
+ # Verify full HTML document structure.
+ assert "" in output
+ assert "" in output
+ assert "" in output
+ assert "" in output
+ assert "" in output
+ assert " None:
+ """
+ Test the individual render helper functions (blank_node,
+ list_node, html_tag, text_node) that form the foundation of
+ the HTML rendering pipeline.
+ """
+ context = Context({})
+ root = HTMLRoot(context)
+
+ # blank_node returns None and does not modify parent.
+ assert blank_node(context, root, BlankNode()) is None
+ assert len(list(root.children)) == 0
+
+ # list_node returns the parent (for child traversal).
+ ln = ListNode()
+ assert list_node(context, root, ln) is root
+
+ # html_tag appends the tag and returns None.
+ tag = HTMLTag("div", {"class": "test"})
+ assert html_tag(context, root, tag) is None
+ assert tag in root.children
+
+ # text_node appends the text and returns None.
+ tn = TextNode("hello")
+ assert text_node(context, root, tn) is None
+ assert tn in root.children
diff --git a/tests/test_html_nodes.py b/tests/test_html_nodes.py
new file mode 100644
index 0000000..e8cd8bd
--- /dev/null
+++ b/tests/test_html_nodes.py
@@ -0,0 +1,334 @@
+# Copyright (C) 2026 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+"""Tests for HTML node types: TextNode, HTMLTag, HTMLRoot."""
+
+import pytest
+
+from docc.context import Context
+from docc.document import BlankNode
+from docc.plugins.html import HTMLRoot, HTMLTag, TextNode
+
+# ---------------------------------------------------------------------------
+# TextNode
+# ---------------------------------------------------------------------------
+
+
+def test_text_node_init() -> None:
+ node = TextNode("hello")
+ assert node._value == "hello"
+
+
+def test_text_node_children_empty() -> None:
+ node = TextNode("test")
+ assert tuple(node.children) == ()
+
+
+def test_text_node_replace_child_raises() -> None:
+ node = TextNode("test")
+ with pytest.raises(TypeError, match="text nodes have no children"):
+ node.replace_child(BlankNode(), BlankNode())
+
+
+def test_text_node_repr() -> None:
+ node = TextNode("hello world")
+ assert repr(node) == "'hello world'"
+
+
+def test_text_node_repr_double_quote() -> None:
+ node = TextNode('say "hello"')
+ assert repr(node) == "'say \"hello\"'"
+
+
+def test_text_node_repr_single_quote() -> None:
+ node = TextNode("it's")
+ assert repr(node) == '"it\'s"'
+
+
+def test_text_node_html_entities() -> None:
+ text = TextNode("<script>")
+ assert text._value == "<script>"
+
+
+def test_text_node_unicode() -> None:
+ text = TextNode("Hello \u00e9\u00e8\u00ea")
+ assert "\u00e9" in text._value
+
+
+def test_text_node_special_characters() -> None:
+ text = TextNode("")
+ assert text._value == ""
+
+
+# ---------------------------------------------------------------------------
+# HTMLTag
+# ---------------------------------------------------------------------------
+
+
+def test_html_tag_init() -> None:
+ tag = HTMLTag("div")
+ assert tag.tag_name == "div"
+ assert tag.attributes == {}
+ assert list(tag.children) == []
+
+
+def test_html_tag_init_with_attributes() -> None:
+ tag = HTMLTag("a", {"href": "/test", "class": "link"})
+ assert tag.attributes["href"] == "/test"
+ assert tag.attributes["class"] == "link"
+
+
+def test_html_tag_append_child() -> None:
+ parent = HTMLTag("div")
+ existing = HTMLTag("p")
+ parent.append(existing)
+ child = HTMLTag("span")
+ parent.append(child)
+ children = list(parent.children)
+ assert children[-1] is child
+
+
+def test_html_tag_append_text() -> None:
+ tag = HTMLTag("p")
+ existing = HTMLTag("span")
+ tag.append(existing)
+ text = TextNode("hello")
+ tag.append(text)
+ children = list(tag.children)
+ assert children[-1] is text
+
+
+def test_html_tag_replace_child() -> None:
+ parent = HTMLTag("div")
+ before = HTMLTag("header")
+ old = HTMLTag("span")
+ after = HTMLTag("footer")
+ parent.append(before)
+ parent.append(old)
+ parent.append(after)
+
+ parent.replace_child(old, new := HTMLTag("p"))
+ children = list(parent.children)
+ assert old not in children
+ assert children.index(new) == 1
+
+
+def test_html_tag_replace_child_duplicate() -> None:
+ parent = HTMLTag("div")
+ child = HTMLTag("a")
+ parent.append(child)
+ parent.append(child)
+
+ new = HTMLTag("em")
+ parent.replace_child(child, new)
+
+ children = list(parent.children)
+ assert child not in children
+ assert children.count(new) == 2
+
+
+def test_html_tag_multiple_children() -> None:
+ parent = HTMLTag("div")
+ first_child = HTMLTag("span")
+ second_child = HTMLTag("p")
+ text = TextNode("text")
+
+ parent.append(first_child)
+ parent.append(second_child)
+ parent.append(text)
+
+ assert len(list(parent.children)) == 3
+
+
+def test_html_tag_repr() -> None:
+ tag = HTMLTag("div")
+ assert repr(tag) == ""
+
+
+def test_html_tag_repr_with_attributes() -> None:
+ tag = HTMLTag("a", {"href": "/test"})
+ result = repr(tag)
+ assert "
None:
+ tag = HTMLTag("div", {"data-value": 'test"quote'})
+ result = repr(tag)
+ assert """ in result
+
+
+def test_html_tag_repr_none_attribute() -> None:
+ tag = HTMLTag("input", {"disabled": None})
+ result = repr(tag)
+ assert "disabled" in result
+
+
+def test_html_tag_repr_none_and_string_attributes() -> None:
+ tag = HTMLTag("input", {"disabled": None, "type": "text"})
+ result = repr(tag)
+ assert "disabled" in result
+ assert 'type="text"' in result
+
+
+def test_html_tag_repr_empty_attribute() -> None:
+ tag = HTMLTag("div", {"data-empty": ""})
+ result = repr(tag)
+ assert 'data-empty=""' in result
+
+
+def test_html_tag_repr_multiple_attributes() -> None:
+ tag = HTMLTag(
+ "div",
+ {"id": "main", "class": "container", "data-value": "test"},
+ )
+ result = repr(tag)
+ assert "id=" in result
+ assert "class=" in result
+ assert "data-value=" in result
+
+
+# ---------------------------------------------------------------------------
+# HTMLRoot
+# ---------------------------------------------------------------------------
+
+
+def test_html_root_init() -> None:
+ context = Context({})
+ root = HTMLRoot(context)
+ assert list(root.children) == []
+
+
+def test_html_root_append() -> None:
+ context = Context({})
+ root = HTMLRoot(context)
+ tag = HTMLTag("div")
+ root.append(tag)
+ assert tag in root.children
+
+
+def test_html_root_replace_child() -> None:
+ context = Context({})
+ root = HTMLRoot(context)
+ old = HTMLTag("div")
+ new = HTMLTag("span")
+ root.append(old)
+
+ root.replace_child(old, new)
+ assert old not in root.children
+ assert new in root.children
+
+
+def test_html_root_extension() -> None:
+ context = Context({})
+ root = HTMLRoot(context)
+ assert root.extension == ".html"
+
+
+def test_html_root_multiple_children() -> None:
+ context = Context({})
+ root = HTMLRoot(context)
+
+ first_tag = HTMLTag("div")
+ second_tag = HTMLTag("span")
+ text = TextNode("hello")
+
+ root.append(first_tag)
+ root.append(second_tag)
+ root.append(text)
+
+ children = list(root.children)
+ assert len(children) == 3
+ assert children[0] is first_tag
+ assert children[1] is second_tag
+ assert children[2] is text
+
+
+# ---------------------------------------------------------------------------
+# HTMLTag._to_element
+# ---------------------------------------------------------------------------
+
+
+def test_html_tag_to_element_simple() -> None:
+ tag = HTMLTag("div")
+ element = tag._to_element()
+ assert element.tag == "div"
+
+
+def test_html_tag_to_element_children() -> None:
+ parent = HTMLTag("div")
+ child = HTMLTag("span")
+ parent.append(child)
+
+ element = parent._to_element()
+ assert element.tag == "div"
+ children = list(element)
+ assert len(children) == 1
+ assert children[0].tag == "span"
+
+
+def test_html_tag_to_element_text() -> None:
+ tag = HTMLTag("p")
+ tag.append(TextNode("hello"))
+
+ element = tag._to_element()
+ assert element.tag == "p"
+ assert element.text == "hello"
+
+
+def test_html_tag_to_element_nested_text() -> None:
+ parent = HTMLTag("p")
+ parent.append(TextNode("start "))
+ child = HTMLTag("strong")
+ child.append(TextNode("bold"))
+ parent.append(child)
+ parent.append(TextNode(" end"))
+
+ element = parent._to_element()
+ assert element.tag == "p"
+ assert element.text == "start "
+ children = list(element)
+ assert len(children) == 1
+ assert children[0].tag == "strong"
+ assert children[0].text == "bold"
+
+
+def test_html_tag_to_element_deep() -> None:
+ outer = HTMLTag("div")
+ middle = HTMLTag("section")
+ inner = HTMLTag("article")
+ inner.append(TextNode("content"))
+ middle.append(inner)
+ outer.append(middle)
+
+ element = outer._to_element()
+ assert element.tag == "div"
+ section = list(element)[0]
+ assert section.tag == "section"
+ article = list(section)[0]
+ assert article.tag == "article"
+ assert article.text == "content"
+
+
+def test_html_tag_to_element_with_attributes() -> None:
+ tag = HTMLTag("a", {"href": "/link", "class": "nav", "id": "main"})
+ tag.append(TextNode("click"))
+
+ element = tag._to_element()
+ assert element.tag == "a"
+ assert element.attrib["href"] == "/link"
+ assert element.attrib["class"] == "nav"
+ assert element.attrib["id"] == "main"
+ assert element.text == "click"
diff --git a/tests/test_html_parser.py b/tests/test_html_parser.py
new file mode 100644
index 0000000..e5dac4e
--- /dev/null
+++ b/tests/test_html_parser.py
@@ -0,0 +1,330 @@
+# Copyright (C) 2026 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+"""Tests for HTMLParser, _ElementTreeVisitor, and _make_relative."""
+
+from pathlib import PurePath
+
+import pytest
+
+from docc.context import Context
+from docc.document import BlankNode
+from docc.plugins.html import (
+ HTMLParser,
+ HTMLTag,
+ TextNode,
+ _ElementTreeVisitor,
+ _make_relative,
+)
+
+# ---------------------------------------------------------------------------
+# HTMLParser
+# ---------------------------------------------------------------------------
+
+
+def test_parser_simple_tag() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("hello
")
+
+ children = list(parser.root.children)
+ assert len(children) == 1
+ child = children[0]
+ assert isinstance(child, HTMLTag)
+ assert child.tag_name == "div"
+
+
+def test_parser_nested_tags() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("text
")
+
+ children = list(parser.root.children)
+ assert len(children) == 1
+ div = children[0]
+ assert isinstance(div, HTMLTag)
+
+ span = list(div.children)[0]
+ assert isinstance(span, HTMLTag)
+ assert span.tag_name == "span"
+
+
+def test_parser_with_attributes() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed('click')
+
+ children = list(parser.root.children)
+ anchor = children[0]
+ assert isinstance(anchor, HTMLTag)
+ assert anchor.attributes["href"] == "/test"
+ assert anchor.attributes["class"] == "link"
+
+
+def test_parser_text_content() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("hello world
")
+
+ children = list(parser.root.children)
+ p = children[0]
+ assert isinstance(p, HTMLTag)
+ text_children = list(p.children)
+ assert len(text_children) == 1
+ text_child = text_children[0]
+ assert isinstance(text_child, TextNode)
+ assert text_child._value == "hello world"
+
+
+def test_parser_multiple_elements() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("one
two
")
+
+ children = list(parser.root.children)
+ assert len(children) == 2
+
+
+def test_parser_empty_string() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("")
+
+ assert list(parser.root.children) == []
+
+
+def test_parser_self_closing_tag() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("
")
+
+ children = list(parser.root.children)
+ assert len(children) == 1
+ assert isinstance(children[0], HTMLTag)
+
+
+def test_parser_self_closing_tag_with_slash() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("
")
+
+ children = list(parser.root.children)
+ assert len(children) == 1
+ child = children[0]
+ assert isinstance(child, HTMLTag)
+ assert child.tag_name == "br"
+
+
+def test_parser_boolean_attribute() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed('')
+
+ children = list(parser.root.children)
+ input_elem = children[0]
+ assert isinstance(input_elem, HTMLTag)
+ assert "disabled" in input_elem.attributes
+
+
+def test_parser_mixed_content() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("Text bold more text
")
+
+ children = list(parser.root.children)
+ p = children[0]
+ assert isinstance(p, HTMLTag)
+ p_children = list(p.children)
+ assert len(p_children) == 3
+
+
+def test_parser_deeply_nested() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ html = ""
+ parser.feed(html)
+
+ children = list(parser.root.children)
+ assert len(children) == 1
+
+
+def test_parser_special_characters() -> None:
+ context = Context({})
+ parser = HTMLParser(context)
+ parser.feed("<script>
")
+
+ children = list(parser.root.children)
+ p = children[0]
+ assert isinstance(p, HTMLTag)
+ text_children = list(p.children)
+ text_child = text_children[0]
+ assert isinstance(text_child, TextNode)
+ assert "