From 3bff12b96612be4e47e20d880d3ba9e57e8bf713 Mon Sep 17 00:00:00 2001
From: n5m <72841454+n5m@users.noreply.github.com>
Date: Mon, 9 Nov 2020 11:20:55 +0000
Subject: [PATCH] improve Testament docs (#15881)

* fix mentions of recursive test discovery

* document that {.fatal.} pragmas cannot be caught
---
 doc/testament.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/testament.rst b/doc/testament.rst
index 18501f4cd8..09c248d1fd 100644
--- a/doc/testament.rst
+++ b/doc/testament.rst
@@ -58,12 +58,12 @@ Running all tests from a directory
 
   $ testament pattern "tests/*.nim"
 
-To recursively search for all tests in a directory, use
+To search for tests deeper in a directory, use
 
 .. code::
 
-  $ testament pattern "tests/**/*.nim"
-
+  $ testament pattern "tests/**/*.nim"    # one level deeper
+  $ testament pattern "tests/**/**/*.nim" # two levels deeper
 
 HTML Reports
 ============
@@ -89,7 +89,9 @@ Example "template" **to edit** and write a Testament unittest:
     # Options:
     #   "compile": expect successful compilation
     #   "run": expect successful compilation and execution
-    #   "reject": expect failed compilation
+    #   "reject": expect failed compilation. The "reject" action can catch
+    #             {.error.} pragmas but not {.fatal.} pragmas because
+    #             {.fatal.} pragmas guarantee that compilation will be aborted.
     action: "run"
 
     # The exit code that the test is expected to return. Typically, the default