Skip to content

Testing and CI

Use this guide when adding fixtures, reproducing output regressions or changing CI. The contributing guide contains development setup, compatibility policy and the pull request process. For user-facing configuration and required diagram tools, see Images and diagrams.

Run the maintained suite

Install Doxygen and the locked development environment from the contributing guide, then run from the repository root:

uv run --locked --extra dev pytest tests/ -q
uv run --locked --extra dev pre-commit run --all-files

tests/ is maintained; tests-old/ contains historical experiments. pytest's integration marker selects the real Doxygen/MkDocs builds. The remaining tests include focused parser/copier checks, packaging and runner failure tests. The locked Python environment does not pin OS tools such as Doxygen.

Integration tests

Small, repository-owned C++ and MkDocs projects live under tests/integration/fixtures/. The pytest builder copies each fixture to a fresh temporary directory and invokes the current interpreter's mkdocs build --clean --strict with real Doxygen. Generated XML, Markdown, HTML, caches and a build.log stay in that directory; the fixture and developer caches are not modified. Output is streamed to the log even on failure or timeout. On the Linux CI runners, a timeout terminates the entire build process group, including Doxygen. Windows uses taskkill /T; that cleanup path is not covered by the Linux process-lifetime regression test. The subprocess receives a minimal environment without inherited credentials, and imports MkDoxy from the candidate checkout. This environment is for reproducibility, not a sandbox for untrusted code.

Run only integration tests or the remaining tests with:

uv run --locked --extra dev pytest tests/ -m integration -v
uv run --locked --extra dev pytest tests/ -m "not integration"

The existing pytest tests/ CI command includes both. Doxygen must be on PATH; a missing executable, a build timeout or a failed strict build fails the test rather than silently skipping it. A nonzero Doxygen exit status fails the build and reports its stdout and stderr even if XML was already generated. Use pytest's --basetemp option to choose a location for retained artifacts (pytest clears that directory before the run). The OS-provided Doxygen version is not locked; include its version when reporting failures. External demo builds remain a broader smoke test, not the source of these focused fixtures.

Parameter directions

The parameter fixture covers names, descriptions, unannotated parameters, and [in], [out], [in,out] annotations. Tests verify the input XML and the resulting Markdown and HTML, including the actual API hyperlink and its target. A doxy.api.class.method snippet also verifies all three directions and an unannotated parameter in the rendered HTML. Directions render before parameter names as [in], [out] and [in/out]; an unannotated parameter keeps its existing output. These are normal assertions, without expected-failure marks.

The navigation fixture covers nested namespaces and classes, nested groups, related pages and source directories. Tests require every supported compound in the Doxygen index to appear once in links.md, check parent/child list nesting in HTML, and resolve every summary link to an actual generated page. Class and namespace enumeration indexes retain the class_member_enums.md and namespace_member_enums.md filenames used by navigation. Builds cover directory and flat URLs, with XML source listings enabled and disabled; source-code links are emitted only when a source page exists. Navigation labels render as literal text. Regression cases include Markdown link delimiters in real page/group titles, HTML and autolink syntax, backslashes, entities, formatting markers and line breaks; titles cannot add a different navigation destination.

Paragraph titles

The paragraph_titles fixture covers Doxygen @par sections with plain, bold, mixed, italic and code titles, as well as untitled paragraphs. Titles render as bold headings with inline formatting retained; bold content is not wrapped in duplicate strong markers. Empty titles emit no empty emphasis. Tests check the actual XML shape and the generated Markdown and HTML, while preserving standard note, warning and see-also labels. Focused parser tests also cover whitespace-only and empty markup titles, reference labels resolved from the symbol cache, nested bold formatting and whitespace inside edge inline elements.

Image assets

The image fixture uses Doxygen @image comments and seven owned, renderable SVG, PNG, JPG, JPEG, animated GIF, BMP and WebP inputs (JPG/JPEG share an encoding). Tests resolve the actual HTML image URL to a site file and compare its bytes with the source asset. They cover default and nested api-path, the default cache location and custom save-api, and both directory and flat HTML URLs. The typed BuildOptions passed to build_project selects these variants. An optional prepare callback modifies only the temporary fixture copy before loading configuration, for example to reproduce existing asset collisions; fixtures keep a single project named api. Focused copier tests separately cover nested XML assets and supported extensions because Doxygen itself may flatten image paths in its XML output. Regression cases also cover overlapping XML/API paths, copy failures, source and destination symlink escapes, reference-based publication, persistent image-cache invalidation, failed-build retries and identical versus conflicting existing docs assets. See the fixture README and optional generate_assets.py for image provenance. The separate demo-projects/diagrams/ examples show native Doxygen-generated graphs; these are not automatically rendered by MkDoxy and require Graphviz to regenerate.

CI checks and permissions

CI uses distinct check names: pre-commit, pytest (Python X.Y), docs (Python X.Y) and demo (Python X.Y). The matrix checks cover the Python versions listed in the workflows. Keep these names stable once they are required by branch protection. pre-commit retains its existing name so the current required check continues to run during the transition.

Versioned workflows default to contents: read. Test and lint checkouts do not persist Git credentials. Only the documentation deployment job has contents: write and persisted credentials, needed by mkdocs gh-deploy to push gh-pages; that workflow runs only on pushes to main. Actions are pinned to full commit SHAs. Review the source and compatibility when updating a pin.

Workflow changes do not update GitHub's repository settings. After the new check names have appeared in a successful pull request run, the owner can add all matrix checks to the required checks for main. Do not require a deployment check that runs only after a merge, and do not remove the existing lint gate before its replacement has run successfully.