Add base test coverage by danceratopz · Pull Request #37 · SamWilsn/docc

danceratopz · 2026-02-23T20:59:33Z

Adds comprehensive test coverage to help validate planned subsequent optimizations.
Enable pytest-cov for coverage reports.
Add a developer section to the README.

- Use explicit patterns instead of recursive ** globs. - Setuptools doesn't reliably include files with ** in sdist builds.

- Add dedicated test extras with pytest and pytest-cov.

- Add test extras to both test and type environments so pytest and pytest-cov are available alongside lint deps.

- Configure pytest to run with coverage enabled. - Set minimum coverage threshold to 80%. - Exclude common non-testable patterns from coverage.

- Add tests for CLI, settings, context, and document modules. - Add tests for plugin loader and transform pipeline. - Add tests for HTML, mistletoe, and verbatim plugins. - Add end-to-end HTML rendering pipeline tests. - Add tests for Python CST parsing and node types. - Add tests for references, search, and resources plugins. - Add integration tests for end-to-end workflows. - Add behavior-level pipeline contract tests. - Achieve 90% code coverage.

SamWilsn

Partial review. 18 more files to go!

SamWilsn · 2026-02-24T18:41:56Z

tests/test_build_discover.py

@@ -0,0 +1,173 @@
+# Copyright (C) 2025 Ethereum Foundation


Should these be 2026?

SamWilsn · 2026-02-24T18:44:59Z

tests/test_build_discover.py

+@pytest.fixture
+def temp_dir() -> Iterator[Path]:
+    with tempfile.TemporaryDirectory() as td:
+        yield Path(td)


Would https://docs.pytest.org/en/stable/how-to/tmp_path.html be useful here?

SamWilsn · 2026-02-24T18:45:56Z

tests/test_build_discover.py

+    _path: PurePath
+
+    def __init__(self, path: Optional[PurePath] = None) -> None:
+        self._path = path if path is not None else PurePath("mock.py")


Suggested change

self._path = path if path is not None else PurePath("mock.py")

self._path = PurePath("mock.py") if path is None else path

The negation adds cognitive load, IMO

SamWilsn · 2026-02-24T18:47:29Z

tests/test_build_discover.py

+        settings = Settings(temp_dir, {"tool": {"docc": {}}})
+        plugin_settings = settings.for_plugin("test")


Fixture maybe?

SamWilsn · 2026-02-24T18:49:21Z

tests/test_build_discover.py

+class TestDiscover:
+    def test_concrete_discover(self, temp_dir: Path) -> None:
+        settings = Settings(temp_dir, {"tool": {"docc": {}}})
+        plugin_settings = settings.for_plugin("test")
+
+        discover = ConcreteDiscover(plugin_settings)
+        sources = list(discover.discover(frozenset()))
+
+        assert len(sources) == 1
+        assert isinstance(sources[0], MockSource)


Is this intentionally testing ConcreteDiscover, like the one defined in this file?

SamWilsn · 2026-02-24T21:18:42Z

tests/test_document.py

+class TestBlankNode:
+    def test_children_returns_empty_tuple(self) -> None:
+        node = BlankNode()
+        assert tuple(node.children) == ()
+
+    def test_replace_child_raises_type_error(self) -> None:
+        node = BlankNode()
+        with pytest.raises(TypeError):
+            node.replace_child(BlankNode(), BlankNode())
+
+    def test_repr(self) -> None:
+        node = BlankNode()
+        assert repr(node) == "<blank>"
+
+    def test_bool_is_false(self) -> None:
+        node = BlankNode()
+        assert bool(node) is False


I feel like there are some base operations that all nodes need to implement. Would parameterization help here?

SamWilsn · 2026-02-24T21:25:44Z

tests/test_document.py

+class RecordingVisitor(Visitor):
+    events: List[str]
+
+    def __init__(self) -> None:
+        self.events = []
+
+    @override
+    def enter(self, node: Node) -> Visit:
+        self.events.append(f"enter:{repr(node)}")
+        return Visit.TraverseChildren
+
+    @override
+    def exit(self, node: Node) -> None:
+        self.events.append(f"exit:{repr(node)}")
+
+
+class SkippingVisitor(Visitor):
+    events: List[str]
+
+    def __init__(self) -> None:
+        self.events = []
+
+    @override
+    def enter(self, node: Node) -> Visit:
+        self.events.append(f"enter:{repr(node)}")
+        return Visit.SkipChildren
+
+    @override
+    def exit(self, node: Node) -> None:
+        self.events.append(f"exit:{repr(node)}")


Suggested change

class RecordingVisitor(Visitor):

events: List[str]

def __init__(self) -> None:

self.events = []

@override

def enter(self, node: Node) -> Visit:

self.events.append(f"enter:{repr(node)}")

return Visit.TraverseChildren

@override

def exit(self, node: Node) -> None:

self.events.append(f"exit:{repr(node)}")

class SkippingVisitor(Visitor):

events: List[str]

def __init__(self) -> None:

self.events = []

@override

def enter(self, node: Node) -> Visit:

self.events.append(f"enter:{repr(node)}")

return Visit.SkipChildren

@override

def exit(self, node: Node) -> None:

self.events.append(f"exit:{repr(node)}")

class RecordingVisitor(Visitor):

returns: ClassVar[Visit] = Visit.TraverseChildren

events: List[Tuple[Literal["enter", "exit"], int]]

def __init__(self) -> None:

self.events = []

@override

def enter(self, node: Node) -> Visit:

self.events.append(("enter", id(node)))

return self.returns

@override

def exit(self, node: Node) -> None:

self.events.append(("exit", id(node)))

class SkippingVisitor(RecordingVisitor):

returns: ClassVar[Visit] = Visit.SkipChildren

Two major suggestions: use id instead of repr because you can check object identity, and inherit instead of re-implementing.

Untested!

SamWilsn · 2026-02-24T21:27:18Z

tests/test_document.py

+        visitor = RecordingVisitor()
+        node.visit(visitor)
+
+        assert visitor.events == ["enter:<blank>", "exit:<blank>"]


Then this would look something like:

Suggested change

assert visitor.events == ["enter:<blank>", "exit:<blank>"]

assert visitor.events == [

("enter", id(node)),

("exit", id(node)),

]

SamWilsn · 2026-02-24T21:31:57Z

pyproject.toml

+[tool.pytest.ini_options]
+# term-missing shows uncovered line numbers in terminal output
+addopts = "--cov=docc --cov-report=term-missing"
+testpaths = ["tests"]


Isn't this the default?

SamWilsn · 2026-02-24T21:33:46Z

setup.cfg


 docc.plugins.html =
-    templates/**
+    templates/*.html


Fix glob patterns in template packaging

b90f62e

- Use explicit patterns instead of recursive ** globs. - Setuptools doesn't reliably include files with ** in sdist builds.

danceratopz marked this pull request as draft February 23, 2026 21:02

danceratopz added 4 commits February 24, 2026 11:21

Add test extras with pytest-cov dependency

0d59b5c

- Add dedicated test extras with pytest and pytest-cov.

Include test extras in tox environments

f748bc6

- Add test extras to both test and type environments so pytest and pytest-cov are available alongside lint deps.

Add pytest and coverage configuration

2373f68

- Configure pytest to run with coverage enabled. - Set minimum coverage threshold to 80%. - Exclude common non-testable patterns from coverage.

Add development section to README

6f0caf1

danceratopz force-pushed the base-test-coverage branch from 16d08cb to df68bf1 Compare February 24, 2026 10:26

danceratopz force-pushed the base-test-coverage branch from df68bf1 to 17b9061 Compare February 24, 2026 12:07

danceratopz marked this pull request as ready for review February 24, 2026 12:07

danceratopz mentioned this pull request Feb 24, 2026

perf: Cache redundant work in transform phase #40

Open

SamWilsn reviewed Feb 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add base test coverage#37

Add base test coverage#37
danceratopz wants to merge 6 commits intoSamWilsn:masterfrom
danceratopz:base-test-coverage

danceratopz commented Feb 23, 2026 •

edited

Loading

Uh oh!

SamWilsn left a comment

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

SamWilsn Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	self._path = path if path is not None else PurePath("mock.py")
	self._path = PurePath("mock.py") if path is None else path

		settings = Settings(temp_dir, {"tool": {"docc": {}}})
		plugin_settings = settings.for_plugin("test")

Comments

Conversation

danceratopz commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SamWilsn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

danceratopz commented Feb 23, 2026 •

edited

Loading