Update testament docs demo, command output, and gotchas (#20756)

doc/testament.md

@@ -17,7 +17,7 @@ so can be useful to run your tests, even the most complex ones.
 Test files location
 ===================
 
-By default, Testament looks for test files on ``"./tests/*.nim"``.
+By default, Testament looks for test files on ``"./tests/category/*.nim"``.
 You can overwrite this pattern glob using `pattern <glob>`:option:.
 The default working directory path can be changed using
 `--directory:"folder/subfolder/"`:option:.
@@ -27,24 +27,30 @@ You can change that using `--nim:"folder/subfolder/nim"`:option:.
 Running JavaScript tests with `--targets:"js"`:option: requires
 a working NodeJS on `PATH`.
 
+Commands
+========
+
+p|pat|pattern <glob>        run all the tests matching the given pattern
+all                         run all tests inside of category folders
+c|cat|category <category>   run all the tests of a certain category
+r|run <test>                run single test file
+html                        generate testresults.html from the database
+
 
 Options
 =======
 
---print                   Also print results to the console
+--print                   print results to the console
---simulate                See what tests would be run but don't run them
+--verbose                 print commands (compiling and running tests)
-                          (for debugging)
+--simulate                see what tests would be run but don't run them (for debugging)
---failing                 Only show failing/ignored tests
+--failing                 only show failing/ignored tests
---targets:"c cpp js objc"
+--targets:"c cpp js objc" run tests for specified targets (default: c)
-                          Run tests for specified targets (default: c)
+--nim:path                use a particular nim executable (default: $PATH/nim)
---nim:path                Use a particular nim executable (default: $PATH/nim)
+--directory:dir           Change to directory dir before reading the tests or doing anything else.
---directory:dir           Change to directory dir before reading the tests
-                          or doing anything else.
 --colors:on|off           Turn messages coloring on|off.
---backendLogging:on|off   Disable or enable backend logging.
+--backendLogging:on|off   Disable or enable backend logging. By default turned on.
-                          By default, turned on.
+--megatest:on|off         Enable or disable megatest. Default is on.
---skipFrom:file           Read tests to skip from ``file`` - one test per
+--skipFrom:file           Read tests to skip from `file` - one test per line, # comments ignored
-                          line, # comments ignored
 
 
 Running a single test
@@ -54,18 +60,21 @@ This is a minimal example to understand the basics,
 not very useful for production, but easy to understand:
 
   ```console
-  $ mkdir tests
+  $ mkdir -p tests/category
-  $ echo "assert 42 == 42" > tests/test0.nim
+  $ echo "assert 42 == 42" > tests/category/test0.nim
-  $ testament run test0.nim
+  $ testament run tests/category/test0.nim
-  PASS: tests/test0.nim C                                    ( 0.2 sec)
+  PASS: tests/category/test0.nim c                           ( 0.2 sec)
-  $ testament r test0
+  $ testament r tests/category/test0
-  PASS: tests/test0.nim C                                    ( 0.2 sec)
+  PASS: tests/category/test0.nim C                           ( 0.2 sec)
   ```
 
 
 Running all tests from a directory
 ==================================
 
+ This will run all tests in the top level tests/ directory. NOTE: these
+ tests are skipped by `testament all`.
+ 
   ```console
   $ testament pattern "tests/*.nim"
   ```