From 2ba946b3417d6ca6130fc885849c4c8831ab852b Mon Sep 17 00:00:00 2001
From: drh <>
Date: Tue, 29 Apr 2025 14:23:21 +0000
Subject: Add the "--fuzzdb FILENAME" to testrunner.tcl as an alternative to
 setting the FUZZDB environment variable (as that can be awkward to do on
 Windows). Further improvements to the testrunner.tcl documentation.

FossilOrigin-Name: 6fb84156a262ff89d1a2d1df6fbfac4c1a43fb55b9d15205508662e2c9b0894f
---
 doc/testrunner.md   | 31 ++++++++++++++++++++++---------
 manifest            | 14 +++++++-------
 manifest.uuid       |  2 +-
 test/testrunner.tcl |  4 ++++
 4 files changed, 34 insertions(+), 17 deletions(-)

diff --git a/doc/testrunner.md b/doc/testrunner.md
index c2808a1e4..d1696e9d1 100644
--- a/doc/testrunner.md
+++ b/doc/testrunner.md
@@ -53,6 +53,14 @@ A useful query might be:
   SELECT * FROM script WHERE state='failed'
 ```
 
+You can get a summary of errors in a prior run by invoking commands like
+these:
+
+```
+  tclsh $(TESTDIR)/testrunner.tcl errors
+  tclsh $(TESTDIR)/testrunner.tcl errors -v
+```
+
 Running the command:
 
 ```
@@ -61,13 +69,17 @@ Running the command:
 
 in the directory containing the testrunner.db database runs various queries
 to produce a succinct report on the state of a running testrunner.tcl script.
-Running:
+A good way to keep and eye on test progress is to run either of the two
+following commands:
 
 ```
   watch tclsh $(TESTDIR)/testrunner.tcl status
+  tclsh $(TESTDIR)/testrunner.tcl status -d 2
 ```
 
-in another terminal is a good way to keep an eye on a long running test.
+Both of the commands above accomplish about the same thing, but the second
+one has the advantage of not requiring "watch" to be installed on your
+system.
 
 Sometimes testrunner.tcl uses the `testfixture` binary that it is run with
 to run tests (see "Binary Tests" below). Sometimes it builds testfixture and
@@ -297,18 +309,19 @@ run a Tcl test script, as <a href=#binary_test_failures>described above</a>.
 <a name=fuzzdb></a>
 ## 3.4 External Fuzzcheck Databases
 
-Testrunner.tcl will also run fuzzcheck against external (out of tree)
-databases, for example fuzzcheck databases generated by dbsqlfuzz.  To do
-this, simply set the FUZZDB environment variable to the name of the external
+Testrunner.tcl will also run fuzzcheck against an external (out of tree)
+database, for example fuzzcheck databases generated by dbsqlfuzz.  To do
+this, simply add the "`--fuzzdb` *FILENAME*" command-line option or set 
+the FUZZDB environment variable to the name of the external
 database.  For large external databases, testrunner.tcl will automatically use
-the "`--slice`" command-line option of fuzzcheck to divide the work up between
-multiple jobs, thus increasing parallelism.
+the "`--slice`" command-line option of fuzzcheck to divide the work up into
+multiple jobs, to increase parallelism.
 
 Thus, for example, to run a full releasetest including an external
 dbsqlfuzz database, run a command like one of these:
 
 ```
-  FUZZDB=../fuzz/20250415.db test/testrunner.tcl releasetest
+  tclsh test/testrunner.tcl releasetest --fuzzdb ../fuzz/20250415.db
   FUZZDB=../fuzz/20250415.db make releasetest
   nmake /f Makefile.msc FUZZDB=../fuzz/20250415.db releasetest
 ```
@@ -318,7 +331,7 @@ databases.  So if you want to run *only* tests involving the external
 database, you can use a command something like this:
 
 ```
-  FUZZDB=../fuzz/20250415.db test/testrunner.tcl releasetest 20250415
+  tclsh test/testrunner.tcl releasetest 20250415 --fuzzdb ../fuzz/20250415.db
 ```
 
 <a name=testrunner_options></a>
diff --git a/manifest b/manifest
index 8616d04e1..8613c0d0f 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Update\stestrunner.tcl\sdocumentation.\s\sFix\stypo\sin\stestrunner.tcl\soutput.
-D 2025-04-29T11:35:51.925
+C Add\sthe\s"--fuzzdb\sFILENAME"\sto\stestrunner.tcl\sas\san\salternative\sto\ssetting\nthe\sFUZZDB\senvironment\svariable\s(as\sthat\scan\sbe\sawkward\sto\sdo\son\sWindows).\nFurther\simprovements\sto\sthe\stestrunner.tcl\sdocumentation.
+D 2025-04-29T14:23:21.489
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
@@ -64,7 +64,7 @@ F doc/jsonb.md ede3238186e3a90bb79d20b2a6a06d0f9429a38e069e9da0efbad0f2ed48b924
 F doc/lemon.html 89ea833a6f71773ab1a9063fbb7fb9b32147bc0b1057b53ecab94a3b30c0aef5
 F doc/pager-invariants.txt 83aa3a4724b2d7970cc3f3461f0295c46d4fc19a835a5781cbb35cb52feb0577
 F doc/tcl-extension-testing.md b88861804fc1eaf83249f8e206334189b61e150c360e1b80d0dcf91af82354f5
-F doc/testrunner.md 41f3ab025a4e6f7505f476c9b3c01a65d109015dc4f4b23797d9c18bed4749be
+F doc/testrunner.md 5ee928637e03f136a25fef852c5ed975932e31927bd9b05a574424ae18c31019
 F doc/trusted-schema.md 33625008620e879c7bcfbbfa079587612c434fa094d338b08242288d358c3e8a
 F doc/vdbesort-memory.md 4da2639c14cd24a31e0af694b1a8dd37eaf277aff3867e9a8cc14046bc49df56
 F doc/vfs-shm.txt 1a55f3f0e7b6745931b117ba5c9df3640d7a0536f532ef0052563100f4416f86
@@ -1734,7 +1734,7 @@ F test/temptable2.test 76821347810ecc88203e6ef0dd6897b6036ac788e9dd3e6b04fd4d163
 F test/temptable3.test d11a0974e52b347e45ee54ef1923c91ed91e4637
 F test/temptrigger.test 38f0ca479b1822d3117069e014daabcaacefffcc
 F test/tester.tcl 463ae33b8bf75ac77451df19bd65e7c415c2e9891227c7c9e657d0a2d8e1074a
-F test/testrunner.tcl dc0230b45cae84607dfcd5b8713966b47c0820fa4718a34d705e1423dedc0b0f x
+F test/testrunner.tcl 614c4a28f7f730acd7bec53e17d76602fb480e0d538b6ec548169e03a093f92d x
 F test/testrunner_data.tcl 8d5fa3851c48bc94e26db0be325202e44f6ca4ed838272b8d5b10c23817621e6
 F test/thread001.test a0985c117eab62c0c65526e9fa5d1360dd1cac5b03bde223902763274ce21899
 F test/thread002.test c24c83408e35ba5a952a3638b7ac03ccdf1ce4409289c54a050ac4c5f1de7502
@@ -2207,8 +2207,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh 49a486c5069de041aedcbde4de178293e0463ae9918ecad7539eedf0ec77a139
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 42bdd7262ec4f8163263e0535c2cc35b526754d77e1f3ccf5b73b0f44d470d9c
-R 79541406257d79ca4afc3c688f589b5b
+P ba8800b4ba0a690c89d9fb96bb9a0d8789d04160ff9c47ea9afb2b403bec7f0b
+R 3acff940d07267222f56625ece4add87
 U drh
-Z 6a36b9638ff8ab1c4c150879edd48798
+Z f1457f63393e45549bde11151130d5cc
 # Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index 1f12a6917..62a2f7c4d 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-ba8800b4ba0a690c89d9fb96bb9a0d8789d04160ff9c47ea9afb2b403bec7f0b
+6fb84156a262ff89d1a2d1df6fbfac4c1a43fb55b9d15205508662e2c9b0894f
diff --git a/test/testrunner.tcl b/test/testrunner.tcl
index a2896fd08..0c6982f42 100755
--- a/test/testrunner.tcl
+++ b/test/testrunner.tcl
@@ -98,6 +98,7 @@ Usage:
     --config CONFIGS         Only use configs on comma-separate list CONFIGS
     --dryrun                 Write what would have happened to testrunner.log
     --explain                Write summary to stdout
+    --fuzzdb FILENAME        Additional external fuzzcheck database
     --jobs NUM               Run tests using NUM separate processes
     --omit CONFIGS           Omit configs on comma-separated list CONFIGS
     --status                 Show the full "status" report while running
@@ -811,6 +812,9 @@ for {set ii 0} {$ii < [llength $argv]} {incr ii} {
     } elseif {($n>2 && [string match "$a*" --omit]) || $a=="-c"} {
       incr ii
       set TRG(omitconfig) [lindex $argv $ii]
+    } elseif {($n>2 && [string match "$a*" --fuzzdb])} {
+      incr ii
+      set env(FUZZDB) [lindex $argv $ii]
     } elseif {[string match "$a*" --stop-on-error]} {
       set TRG(stopOnError) 1
     } elseif {[string match "$a*" --stop-on-coredump]} {
-- 
cgit v1.2.3