GNU bug report logs - #75041
[PATCH] doc/srfi-64: Fix typos and add examples.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 75041 in the body.
You can then email your comments to 75041 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: bug-guile <at> gnu.org
Cc: Arne Babenhauserheide <arne_bab <at> web.de>,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Subject: [PATCH] doc/srfi-64: Fix typos and add examples.
Date: Mon, 23 Dec 2024 13:59:14 +0900

* 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_bab <at> 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

Message #10 received at 75041-done <at> debbugs.gnu.org (full text, mbox):

From: lloda <lloda <at> sarc.name>
To: 75041-done <at> debbugs.gnu.org
Subject: Re: [PATCH] doc/srfi-64: Fix typos and add examples.
Date: Fri, 24 Jan 2025 19:29:17 +0100

Applied in f109baebc005952a58726ee80b56bc5ef291af92. 

Thanks

Message #13 received at 75041 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: lloda <lloda <at> sarc.name>
Cc: 75041 <at> debbugs.gnu.org
Subject: Re: bug#75041: closed (Re: [PATCH] doc/srfi-64: Fix typos and add
 examples.)
Date: Sat, 25 Jan 2025 10:17:09 +0900

Hello,

[...]

> From: lloda <lloda <at> sarc.name>
> Subject: Re: [PATCH] doc/srfi-64: Fix typos and add examples.
> To: 75041-done <at> debbugs.gnu.org
> Date: Fri, 24 Jan 2025 19:29:17 +0100 (6 hours, 47 minutes, 1 second ago)
>
>
> Applied in f109baebc005952a58726ee80b56bc5ef291af92. 

Excellent, thank you!

-- 
Maxim

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.