* doc/ref/srfi-modules.texi (SRFI-64 Writing Basic Test Suites): Fix
typo. Add default test runner example. Add test-approximate and
test-error examples. Document valid error types in Guile for test-error.
(SRFI-64 Conditonal Test Suites and Other Advanced Features): Fix typo.
Suggested-by: Arne Babenhauserheide <arne_...@web.de>
---
doc/ref/srfi-modules.texi | 83 +++++++++++++++++++++++++++++++++++++--
1 file changed, 80 insertions(+), 3 deletions(-)
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index d77bc1c90..537ec9059 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -5387,13 +5387,31 @@ is also easy to add new tests, without having to name
individual tests
(though that is optional).
Test cases are executed in the context of a @dfn{test runner}, which is
-a object that accumulates and reports test results. This specification
+an object that accumulates and reports test results. This specification
defines how to create and use custom test runners, but implementations
should also provide a default test runner. It is suggested (but not
required) that loading the above file in a top-level environment will
cause the tests to be executed using an implementation-specified default
test runner, and @code{test-end} will cause a summary to be displayed in
-an implementation-specified manner.
+an implementation-specified manner. The SRFI 64 implementation used in
+Guile provides such a default test runner; running the above snippet at
+the REPL prints:
+
+@example
+*** Entering test group: vec-test ***
+$1 = #t
+* PASS:
+$2 = ((pass . 1))
+* PASS:
+$3 = ((pass . 2))
+* PASS:
+$4 = ((pass . 3))
+*** Leaving test group: vec-test ***
+*** Test suite finished. ***
+*** # of expected passes : 3
+@end example
+
+It also returns the @code{<test-runner>} object.
@subsubheading Simple test-cases
@@ -5455,6 +5473,14 @@ once):
(and (>= test-expr (- expected error))
(<= test-expr (+ expected error))))
@end lisp
+
+Here's an example:
+@lisp
+(test-approximate "is 22/7 within 1% of π?"
+ 3.1415926535
+ 22/7
+ 1/100)
+@end lisp
@end deffn
@subsubheading Tests for catching errors
@@ -5492,8 +5518,59 @@ classes:
An implementation that cannot catch exceptions should skip
@code{test-error} forms.
+
+@cindex test-error error types
+@cindex error types, test-error, srfi-64
+The SRFI-64 implementation in Guile supports specifying @var{error-type}
+as either:
+@iterate
+@item
+@code{#f}, meaning the test is @emph{not} expected to produce an error
+@item
+@code{#t}, meaning the test is expected to produce an error, of any type
+@item
+A native exception type, as created via @code{make-exception-type} or
+@code{make-condition-type} from SRFI-35
+@item
+A predicate, which will be applied to the exception caught
+to determine whether is it of the right type
+@item
+A symbol, for the exception kind of legacy
+@code{make-exception-from-throw} style exceptions.
@end deffn
+Below are some examples valid in Guile:
+
+@lisp
+(test-error "expect old-style exception kind"
+ 'numerical-overflow
+ (/ 1 0))
+@end lisp
+
+@lisp
+(use-modules (ice-9 exceptions)) ;for standard exception types
+
+(test-error "expect a native exception type"
+ &warning
+ (raise-exception (make-warning)))
+
+(test-error "expect a native exception, using predicate"
+ warning?
+ (raise-exception (make-warning)))
+@end lisp
+
+@lisp
+(use-modules (srfi srfi-35))
+
+(test-error "expect a serious SRFI 35 condition type"
+ &serious
+ (raise-exception (condition (&serious))))
+
+(test-error "expect a serious SRFI 35 condition type, using predicate"
+ serious-condition?
+ (raise-exception (condition (&serious))))
+@end lisp
+
@subsubheading Testing syntax
Testing syntax is tricky, especially if we want to check that invalid
@@ -5617,7 +5694,7 @@ or specifying that some tests are @emph{expected} to fail.
@subsubheading Test specifiers
Sometimes we want to only run certain tests, or we know that certain
-tests are expected to fail. A @dfn{test specifier} is one-argument
+tests are expected to fail. A @dfn{test specifier} is a one-argument
function that takes a test-runner and returns a boolean. The specifier
may be run before a test is performed, and the result may control
whether the test is executed. For convenience, a specifier may also be
base-commit: f6359a4715d023761454f1bf945633ce4cca98fc
--
2.46.0
