Testing utilities¶
sphinx-design ships a small, semi-public helper module,
sphinx_design.testing, for downstream extensions that write
doctree regression
tests (for example sphinx-design-elements).
The module has no dependency on pytest or any test extras, so it can be
imported with only sphinx_design installed.
normalize_doctree_xml¶
normalize_doctree_xml(text: str, extra_attributes: Sequence[str] = ()) -> str
Normalizes pretty-printed doctree XML (e.g. from document.pformat()) so that
a single set of regression fixtures works across docutils versions: docutils
0.22+ serializes boolean node attributes as "1"/"0" rather than
"True"/"False", and this rewrites the former back to the latter. On
docutils < 0.22 it is a no-op.
Only known boolean attributes are rewritten, so non-boolean "1"/"0" values
(such as text content or numeric attributes) are left untouched. Pass
extra_attributes to also normalize boolean attributes on your own custom
nodes.
SphinxBuilder¶
The SphinxBuilder wrapper used by sphinx-design’s own sphinx_builder
pytest fixture is also exposed. It is a thin wrapper around a
sphinx.testing.util.SphinxTestApp that you construct yourself (e.g. with
sphinx’s make_app pytest fixture) — it does not create the project
scaffolding for you — giving convenient access to build status/warnings and
doctrees with source paths normalized for regression comparison.
Stability¶
This is a semi-public testing API:
the signatures of the helpers are covered by the deprecation policy;
the exact output of
normalize_doctree_xmlis not guaranteed to be stable across docutils versions – it exists only to smooth over docutils’ changing serialization for regression testing.
Example¶
from sphinx_design.testing import normalize_doctree_xml
# ``doctree`` is a docutils document, e.g. from a Sphinx build
xml = normalize_doctree_xml(doctree.pformat())
file_regression.check(xml, extension=".xml")
