Skip to main content

Section 45.2 Testing Procedures

When developing a new feature or trying to fix a bug, it can be helpful to test a “before” version of some output format versus a current or “after” version. Sometimes you can lay the groundwork for a new feature by adding some code which has zero effect, but leaves a place where a small addition enables the feature. Then you can be somewhat confident your additions will also not ruin existing (desirable) behavior. Here are some suggestions for doing this with PreTeXt.

  • Make a “before” version before you start. Or do a git stash save to put away uncommitted changes and then make that initial version. Use git stash pop to bring the changes back. You can also temporarily git checkout 1234abcd some commit, and git checkout topic-branch to come back. You can have sample-article.tex.old around to compare with a new and constantly updated sample-article.tex. I routinely remove *.tex between tests, so the *.tex.old version is named so it does not get deleted.

  • The sample-article.xml document is meant to have one of most everything and lots of extreme examples. If your changes affect chapters, and other aspects of a book, then the sample-book.xml document can also be used.

  • Be careful about adding new content since you can get a lot of automatically-generated id's that change, making it hard to see real changes. By managing location (early in a list of commits) and building at specific commits you can test new code that needs new sample uses.

  • output is one big file. Use the debug.chunk string parameter, set to 0 to get one big HTML file.

  • Use the debug.datedfiles string parameter set to no so that file headers (knowls!) do not all have spurious changes.

  • git diff sample-article.tex.old sample-article.tex works well, and oftentimes it works even better with --word-diff. You really want your test output off in some scratch directory. If not, be careful, and you may need the --no-index option so you are not fooled by no apparent changes. (Those options need a double-dash to lead, they look like one right now.)

  • Having <today/> and <timeofday/> in your test document you can be sure there is always at least one or two changes, and prevent some confusion due to mistakes.

  • When testing HTML output, especially for chunking or knowls, putting two versions in different parallel directories will allow git to compare the entire directories with git diff /tmp/before /tmp/after.

  • Every number is hard-coded in HTML output, so changes to numbering are best tested there. The conversion may react differently (a mix of hard-coded and automatically-generated numbers), so should also be tested.

It can be very surprising how many subtle bugs can be revealed by very small, or very few, changes discovered by these procedures.