Skip to content

TESTING.md

Latest commit

 

History

History
96 lines (78 loc) · 5.01 KB

TESTING.md

File metadata and controls

96 lines (78 loc) · 5.01 KB
Raw

Building and testing wiseref

Run commands from the package directory. make sty extracts the runtime file; make doc builds both manuals with LuaLaTeX. The Chinese manual uses ctex's plain scheme and Fandol; the English manual uses Latin Modern without a CJK backend. All fonts used by the manuals are distributed with TeX Live.

The driver also uses ltxdoc, geometry, amsmath, booktabs, listings, xcolor, caption, titlesec, fancyhdr, enumitem, and hyperref. These are documentation dependencies, not wiseref runtime dependencies.

Standard suites

Tests need Python 3.10 or later, pypdf, pypdfium2, and the TeX engines used by each suite. make check runs these commands with timestamped work directories:

make sty
python3 test/run.py --work /tmp/wiseref-tests
python3 test/lifecycle.py --work /tmp/wiseref-lifecycle
python3 test/langs.py --work /tmp/wiseref-langs
python3 test/builtins.py --work /tmp/wiseref-builtins
python3 test/ctex.py --work /tmp/wiseref-ctex

Work directories must not already exist.

CI dependencies, including PyYAML for workflow/policy checks, are pinned in requirements-ci.txt. See CI.md for the multi-release matrix, scheduled integrations, summaries, and artifact retention.

  • run.py: 36 standard-class combinations compare labels, PDF text, character positions, and links with and without wiseref. Six API combinations check 34 outputs, all three link modes, starred calls, and group restoration.
  • lifecycle.py: amsmath loading order, auxiliary-file convergence, and removal of wiseref while retaining the existing aux file.
  • langs.py: eight combinations test Babel/polyglossia, document names, custom profiles, aliases, and explicit-setting precedence. Document-name switches are checked at profile/setup level, through nested groups and with unusable name commands. Suffix examples test dynamic names and explicit plurals. An ASCII-affix fixture checks Japanese heading-name placement without CJK fonts.
  • builtins.py: five combinations test the six Latin-script profiles, singular/plural names, ranges, local switches, and 30 aliases. The Lua polyglossia Portuguese local-switch check is skipped if luavlna is absent; explicit Portuguese and the other manager/engine checks still run.
  • ctex.py: 44 combinations test three engines, Chinese/plain schemes, class and package loading order, heading mode, pre-class loading, and manager precedence. Unicode engines use Fandol; pdfLaTeX uses fontset=none with distributed Arphic Type 1 CJK fonts. These fonts belong to the fixtures. Renamed figures and headings also check use-document-name off/on behavior.

make check-doc verifies source extraction and 21 live results in each manual. It checks actual PDF link annotations, first/last destinations, equation-tag targets, and absence of links on starred calls. Layout, font, rerun, and duplicate-destination warnings fail the check.

Optional integration suites

python3 test/ctan.py --download \
  --cache /tmp/wiseref-ctan-cache --work /tmp/wiseref-ctan-results
python3 test/packages.py --work /tmp/wiseref-packages

The class suite downloads missing class sources and test fonts into its cache. It does not install them into the TeX tree. The package suite uses installed packages, Biber for bibliography fixtures, and restricted shell escape with latexminted for highlighting. Use --biber /path/to/biber to select a working backend. A blocked ordinary baseline produces a nonzero exit status.

The package runner also accepts --suite portable|external|extras|tagging|all and --engines. --allow-known-baselines recognizes only the documented comprehensive tagging error in its unloaded baseline; it never marks it as a pass. Unknown or empty case selections are errors in both integration runners.

The recorded runs used TeX Live 2026. See class compatibility and package compatibility for the dated results, configuration requirements, and untested cases. Standalone tests reject other automatic-reference packages; interaction tests load the packages they compare.

CTAN archive

make ctan runs l3build ctan, verifies the manuals in build/doc, checks the CTAN and TDS file lists, and rebuilds the manuals in a temporary directory using only the archive's contents. The archive has a wiseref/ source root and an optional sibling wiseref.tds.zip. Tests and reports remain under test/ in the source root; generated results and local caches are excluded.

test/release.py uses only the Python standard library for packing; its clean build invokes make check-doc, which needs the PDF libraries listed above. All Python scripts here are development tools, not installed runtime commands.

make check-examples extracts the TDS archive into an isolated TEXMFHOME and compiles the included English example with Lua/Xe/pdf engines and the Chinese example with Lua/Xe engines. It checks the resolved runtime path, eight actual outputs per build, valid link destinations, and the unlinked starred reference.