にっき♪: l3buildでテスト

備忘録．

l3buildとは？

LaTeX3 projectによる，LaTeXパッケージ用ビルドツール．Luaで書かれていて，texluaで実行できる．いったん設定を書いておけば，ファイルを自動生成したりTDSに基づいたファイル群を作ってくれたりctanにあげるための.zipファイルを作ってくれたりする（らしい）．

それよりも，気合い入れて作られているのがテストについて．というわけでここでもテストの機能だけ使ってみる．

2021/5/27追記：2021/5/5に更新されて，今までtexlua build.luaと書いていた部分はl3buildに変更されたっぽい．

build.lua

テストなどの設定はbuild.luaというLuaスクリプトに書く．最低限だけ書くとこんな感じになる．

#!/usr/bin/env texlua

-- パッケージ名
module = "jlreq"
-- チェックしたいエンジンの一覧
checkengines = {"luatex","ptex","uptex"}
-- LaTeXのパッケージである
checkformat = "latex"
-- (u)pTeXに対してはGUESS_INPUT_KANJI_ENCODING=0のもとでテストが行われる．
-- テストをUTF-8なファイルにしておきたいので，エンコードをutf8にするオプションを追加．
-- （LuaTeXにも渡されるが警告がでるだけなので気にしないことにする）
-- TeX Live 2018以降はptex/uptexがUTF-8になったので不要
checkopts = "-kanji=utf8 -interaction=nonstopmode"
-- kpsewhichを設定してメインとなるl3build.luaを読み込む
-- 2021/05/27：2021/5/5でこれはいらなくなったっぽい．
-- kpse.set_program_name("kpsewhich")
-- dofile(kpse.lookup("l3build.lua"))

パッケージにあるファイルが書いていないのとかおかしいけど，とりあえずテストのだめだけということで．テストしたいファイルはTEXMFツリーにあって，TeXが見つけられる状態になっているとしておく．

テスト

build.luaと同じフォルダにtestfilesというフォルダを作り（このフォルダ名はbuild.lua内で変数testfiledirを設定することで変更可能）テストを書く．テストファイルの拡張子は.lvtとなる．テストファイルの大雑把な構造は次の通り．

% sample.lvt
\documentclass{jlreq}
% テストに必要なマクロが定義されているファイルを読み込む
\input{regression-test.tex}
\begin{document}
% ... 必要ならばいろいろな準備を書く
\START % テスト開始
% ... いろいろなテストを書く
\end{document}

予期される結果は，拡張子の異なる.tlgファイルに書く．が，直接書くのは結構大変なので自動生成する（後で）．

テストの種類

テストは，ログファイルへの出力を比べることにより行われる．regression-test.texで定義されているマクロを使うことで，特定のフォーマットでログファイルへの出力が行われ，それをl3build.luaがチェックしてくれる．テストの種類はおおまかに三通り．

マクロやレジスタの中身などをチェックする．
ボックスの中身をチェックする．
ページの出力自身をチェックする．

マクロやレジスタの中身などをチェックする

内部で使われているマクロなどをチェックするのはこれ．

\documentclass{article}
\input{regression-test.tex}
\begin{document}
\makeatletter
\newcounter{testcount}
\START % テスト開始
\TEST{stepcounter}{% \stepcounterのテストをする
  \OMIT
  \setcounter{testcount}{3}
  \stepcounter{testcount}
  \TIMO % \OMITからここまではテストの出力とは関係ない
  \TYPE{\arabic{testcount}}% チェック用に出力，4のはず
%  \showthe\value{testcount}% こっちでもよい 
}
% \@removeelement{<element>}{<list>}{<cs>}のテスト
% <list>から<element>を消して<cs>に入れる
\TEST{@removeelement}{% 
  \@removeelement{b}{a,b,c}{\@tempa}
  \show\@tempa % チェック用に出力 a,cのはず
}
\end{document}

ボックスの中身をチェックする．

テストしたいものをボックスに入れて\showboxするだけ．

\documentclass{article}
\input{regression-test.tex}
\begin{document}
\makeatletter
\START
\newbox\testbox
\TEST{BOX}{
  \OMIT
  \setbox\testbox=\vbox{\section{ABCDE}}% ボックスに入れて
  \TIMO
  \showbox\testbox% ログに出す
}
\end{document}

ページの出力自身をチェックする

\showoutputを使う．

\documentclass{article}
\input{regression-test.tex}
\begin{document}
\makeatletter
\START
\showoutput
This is a main text\footnote{This is a footnote}.
\end{document}

.tlgファイルの作成

テストを書いたらそこから.tlgファイルを作成する．今後の開発におけるテストではこの.tlgファイルとの比較を行うことになる．

.tlgファイルを作るにはl3buildのsaveを使う．現在の構成は以下の通り．

トップディレクトリにbuild.luaとtestfilesディレクトリが存在する．
testfilesディレクトリにはsample.lvtがある．

このテストではエンジンとしてptex/uptex/luatexを使うので，三種の.tlgを作成する必要がある．ptex用の.tlgを作るには次のようにする．（build.luaのあるディレクトリで実行．）

> l3build save -e ptex sample

これでsample.ptex.tlgがtestfiles内に作られる．ptexの部分をuptexやluatexに変えてその他のファイルも生成する．下のようなファイルが作られるはず．

This is a generated file for the l3build validation system.
Don't change this file in any respect.
============================================================
TEST 1: stepcounter
============================================================
4
============================================================
============================================================
TEST 2: @removeelement
============================================================
> \@tempa=macro:
->a,c.
 ... {b}{a,b,c}{\@tempa } \show \@tempa 
l. ...}
============================================================
(sample.aux)

出力されている結果が正しい（stepcounterのテストでは4，@removeelementのテストではa,c）になっていることを確認しておく．ボックスの中身をチェックする例では次のような中身になっているはず．

This is a generated file for the l3build validation system.
Don't change this file in any respect.
\testbox=\box...
============================================================
TEST 1: BOX
============================================================
> \box...=
\vbox(34.85214+0.0)x345.0
.\penalty -300
.\glue 15.0694 plus 4.30554 minus 0.86108
.\glue(\parskip) 0.0 plus 1.0
.\hbox(9.87999+0.0)x345.0, glue set 262.20004fil
..\hbox(9.27998+0.0)x24.29997
...\glue 0.0
...\OT1/cmr/bx/n/14.4 1
...\glue 16.19998
..\OT1/cmr/bx/n/14.4 A
..\OT1/cmr/bx/n/14.4 B
..\OT1/cmr/bx/n/14.4 C
..\OT1/cmr/bx/n/14.4 D
..\OT1/cmr/bx/n/14.4 E
..\penalty 10000
..\glue(\parfillskip) 0.0 plus 1.0fil
..\glue(\rightskip) 0.0
.\write1{\@writefile{toc}{\protect \contentsline {section}{\protect \numberline \ETC.}
.\penalty 10000
.\glue 9.90276 plus 0.86108
! OK.
 ...ion {ABCDE}}\TIMO \showbox \testbox 
l. ...}
============================================================
(sample.aux)

この中身が正しいものであることを確認するのは困難なので，一度\showbox\testboxを\box\testboxなどして通常のコンパイルを行い，出力結果が予期されているものであることを確認しておきましょう．

テストの実行

トップディレクトリで

> l3build check

とすると，testfilesディレクトリ内のすべてのテストが実行される．最後に「All checks passed」と出ればすべてのテストにパスしたことになる．そうでない場合はトップディレトリ内のbuild/test内にテストの実行結果（正しいはずの.tlgと今回のテストにおける.logファイル，および二つをdiffした結果）があるので，それを参照しつつ直す．

PDFでのテスト

-pをつけるとPDFを比較するというテストができるらしい．つまり

> l3build save -e ptex -p sample
> l3build save -e uptex -p sample
> l3build save -e luatex -p sample

として比較対象となるPDFファイルを作成し，

> l3build check -p

としてPDFファイルを比較することによるテストを行う．どのくらい有用なのかは知らないけど……．それとTeX Live 2016以降が必要らしい．

にっき♪

2018年2月3日

l3buildでテスト