| 1 |
% -*- coding: utf-8 -*- |
| 2 |
\documentclass[oneside,12pt]{article} |
| 3 |
\usepackage[a4paper,margin=2cm]{geometry} |
| 4 |
|
| 5 |
\newcommand*{\myversion}{2025A} |
| 6 |
\newcommand*{\mydate}{Version \myversion\ (\the\year-\mylpad\month-\mylpad\day)} |
| 7 |
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi} |
| 8 |
|
| 9 |
\setlength{\parindent}{0pt} |
| 10 |
\setlength{\parskip}{4pt plus 1pt minus 1pt} |
| 11 |
|
| 12 |
\usepackage{codehigh} |
| 13 |
\usepackage{tabularray} |
| 14 |
\UseTblrLibrary{booktabs} |
| 15 |
\usepackage{hyperref} |
| 16 |
\hypersetup{ |
| 17 |
colorlinks=true, |
| 18 |
urlcolor=blue3, |
| 19 |
linkcolor=green3, |
| 20 |
} |
| 21 |
|
| 22 |
\NewDocumentCommand\mypkg{m}{\textcolor{blue3}{\mbox{\ttfamily#1}}} |
| 23 |
\NewDocumentCommand\myopt{m}{\textcolor{brown3}{\mbox{#1}}} |
| 24 |
\NewDocumentCommand\mycmd{m}{\textcolor{green3}{\ttfamily\fakeverb{#1}}} |
| 25 |
\NewDocumentCommand\myfile{m}{\textcolor{purple3}{\mbox{#1}}} |
| 26 |
\NewDocumentCommand\myprg{m}{\textcolor{cyan3}{\mbox{#1}}} |
| 27 |
|
| 28 |
\begin{document} |
| 29 |
|
| 30 |
\title{\sffamily |
| 31 |
\textcolor{green3}{The \texttt{ppmcheckpdf} tool}\\ |
| 32 |
{\large Image-based regression testing for LaTeX packages}% |
| 33 |
} |
| 34 |
\author{% |
| 35 |
Jianrui Lyu ([email protected])% |
| 36 |
%\\\url{https://github.com/lvjr/ppmcheckpdf} |
| 37 |
} |
| 38 |
\date{\mydate} |
| 39 |
\maketitle |
| 40 |
|
| 41 |
The \mypkg{l3build} system is a useful and powerful tool for regression testing. |
| 42 |
With \mypkg{l3build} you normally print the contents of some boxes from \myfile{.lvt} files |
| 43 |
to corresponding \myfile{.tlg} files. Sometimes \LaTeX{} kernel or some package your package |
| 44 |
depends on adds a whatisit or \mycmd{\kern0pt}, and your test files will fail even if |
| 45 |
the PDF files look the same as before and are still correct. |
| 46 |
|
| 47 |
This \mypkg{ppmcheckpdf} tool provides an alternative way for regression testing: |
| 48 |
Instead of printing box contents in \myfile{.lvt} files, you could just convert PDF files |
| 49 |
to PNG files and compare PNG files after \mypkg{l3build} finishes its job. |
| 50 |
|
| 51 |
\section{Installation} |
| 52 |
|
| 53 |
Normally your TeX distribution will copy \mypkg{ppmcheckpdf} files and |
| 54 |
create a binary file \myfile{ppmcheckpdf} when you install this package. |
| 55 |
|
| 56 |
If a manual installation is needed, you could copy \mypkg{ppmcheckpdf} files to TEXMF tree as follows: |
| 57 |
|
| 58 |
\noindent\begin{tblr}{X[font=\ttfamily]X[2,font=\ttfamily]} |
| 59 |
\toprule |
| 60 |
Package file & Where to install it \\ |
| 61 |
\midrule |
| 62 |
ppmcheckpdf.1 & TEXMF/doc/man/man1/ppmcheckpdf.1 \\ |
| 63 |
README.txt & TEXMF/doc/support/ppmcheckpdf/README.txt \\ |
| 64 |
ppmcheckpdf.lua & TEXMF/scripts/ppmcheckpdf/ppmcheckpdf.lua \\ |
| 65 |
\bottomrule |
| 66 |
\end{tblr} |
| 67 |
|
| 68 |
Then create a symbolic link from \myfile{/usr/local/bin/ppmcheckpdf} to \myfile{path/to/ppmcheckpdf.lua} on Linux or MacOS, |
| 69 |
or create a batch file \myfile{ppmcheckpdf.bat} in binary folder of the TeX distribution with these lines on Windows: |
| 70 |
|
| 71 |
\begin{codehigh} |
| 72 |
@echo off |
| 73 |
texlua path\to\ppmcheckpdf.lua %* |
| 74 |
\end{codehigh} |
| 75 |
|
| 76 |
The \mypkg{ppmcheckpdf} tool uses \myprg{pdftoppm} program for image converting. |
| 77 |
This program is installed by default on MiKTeX. For TeX Live, you can install it by running |
| 78 |
\begin{codehigh} |
| 79 |
tlmgr install wintools.windows |
| 80 |
\end{codehigh} |
| 81 |
on Windows, or running |
| 82 |
\begin{codehigh} |
| 83 |
sudo apt-get install poppler-utils |
| 84 |
\end{codehigh} |
| 85 |
on Ubuntu/Debian Linux. |
| 86 |
|
| 87 |
\section{Usages} |
| 88 |
|
| 89 |
You could call \myopt{check} action of \mypkg{ppmcheckpdf} with the folllowing commands |
| 90 |
\begin{codehigh} |
| 91 |
l3build check |
| 92 |
ppmcheckpdf check |
| 93 |
\end{codehigh} |
| 94 |
|
| 95 |
The first run of \mypkg{ppmcheckpdf} will save image and md5 files to \myfile{testfiles} folder, |
| 96 |
and the subsequent runs of it will compare new md5 values with existing md5 values. |
| 97 |
|
| 98 |
You could force \mypkg{ppmcheckpdf} to save new image and md5 files of failed tests to |
| 99 |
\myfile{testfiles} folder by calling \myopt{save} option of it: |
| 100 |
\begin{codehigh} |
| 101 |
l3build check |
| 102 |
ppmcheckpdf save |
| 103 |
\end{codehigh} |
| 104 |
|
| 105 |
Both \myopt{check} and \myopt{save} actions accept \myopt{-c} option, which sets the config to used. |
| 106 |
|
| 107 |
\section{Customizations} |
| 108 |
|
| 109 |
The \myprg{pdftoppm} program supports several types of image files. |
| 110 |
By default the \mypkg{ppmcheckpdf} tool will use \myfile{.png} file, |
| 111 |
and you could change it in \myfile{build.lua} file like this: |
| 112 |
\begin{codehigh} |
| 113 |
imgext = ".ppm" |
| 114 |
\end{codehigh} |
| 115 |
\begin{codehigh} |
| 116 |
imgext = ".pgm" |
| 117 |
\end{codehigh} |
| 118 |
\begin{codehigh} |
| 119 |
imgext = ".pbm" |
| 120 |
\end{codehigh} |
| 121 |
|
| 122 |
\end{document} |