From acd1e0310b32deb55cff221da172ce91c70c8794 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sat, 1 Apr 2023 08:47:26 -0400 Subject: [PATCH] docs: more tweaking of the gold-file instructions --- tests/gold/README.rst | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/tests/gold/README.rst b/tests/gold/README.rst index ec4081825..c90c9eece 100644 --- a/tests/gold/README.rst +++ b/tests/gold/README.rst @@ -12,9 +12,22 @@ current output of the tests into the gold files. When a test fails, the actual output is in the tests/actual directory. Those files are ignored by git. There's a Makefile in the html directory for working with gold files and their -associated support files. If actual outputs have changed so that comparisons -are failing, but the new output is correct, you can use "make update-gold" to -copy the actual output as the new gold files. +associated support files. + +To view the tests/actual files, you need to tentatively copy them to the gold +directories, and then add the supporting files so they can be viewed as +complete output. For example:: + + cp tests/actual/html/contexts/* tests/gold/html/contexts + cd tests/actual/html + make complete + +If the new actual output is correct, you can use "make update-gold" to copy the +actual output as the new gold files. + +If you have changed some of the supporting files (.css or .js), then "make +update-support" will copy the updated files to the tests/gold/html/support +directory for checking test output. If you have added a gold test, you'll need to manually copy the tests/actual files to tests/gold. @@ -27,8 +40,9 @@ again, you can run just the failed tests again with:: The saved HTML files in the html directories can't be viewed properly without the supporting CSS and Javascript files. But we don't want to save copies of those files in every subdirectory. The make target "make complete" in -tests/gold/html will copy the support file so you can open the HTML files to -see how they look. +tests/gold/html will copy the support files so you can open the HTML files to +see how they look. When you are done checking the output, you can use "make +clean" to remove the support files from the gold directories. If the output files are correct, you can update the gold files with "make update-gold". If there are version-specific gold files (for example,