bug#71300: [PATCH v3] doc: Document SRFI 64.

["Dr. Arne Babenhauserheide" via "Bug reports for GUILE, GNU's Ubiquitous Extension Language" <bug-guile@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 4384 bytes --]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
> index 02da3e2f2..4d408d6cb 100644
> --- a/doc/ref/srfi-modules.texi
> +++ b/doc/ref/srfi-modules.texi
> @@ -55,7 +56,7 @@ get the relevant SRFI documents from the SRFI home page
>  * SRFI-60::                     Integers as bits.
>  * SRFI-61::                     A more general `cond' clause
>  * SRFI-62::                     S-expression comments.
> -* SRFI-64::                     A Scheme API for test suites.
> +* SRFI 64::                     A Scheme API for test suites.

If you change this for one, please harmonize the others (with or without
-). Consistency wins here.

> @@ -5290,12 +5291,827 @@ needed to get SRFI-61 itself.  Extended @code{cond} is documented in
…
> +There are other testing frameworks written in Scheme, including
> +@url{https://docs.racket-lang.org/rackunit/, RackUnit}.  However
> +RackUnit is not portable.  It is also a bit on the verbose side.  It
> +would be useful to have a bridge between this framework and RackUnit so
> +RackUnit tests could run under this framework and vice versa.  There
> +exists also at least one Scheme wrapper providing a Scheme interface to
> +the ``standard'' @url{https://www.junit.org/, JUnit} API for Java.  It
> +would be useful to have a bridge so that tests written using this
> +framework can run under a JUnit runner.  Neither of these features are
> +part of this specification.

Is this relevant for Guile?
If not, I’d take the racket specific part out.

> +This API makes use of implicit dynamic state, including an implicit
> +``test runner''.  This makes the API convenient and terse to use, but it
> +may be a little less elegant and ``compositional'' than using explicit
> +test objects, such as JUnit-style frameworks.  It is not claimed to
> +follow either object-oriented or functional design principles, but I
> +hope it is useful and convenient to use and extend.

This sub-sentence ("but I hope...") isn’t needed here, I think.

> +Test cases are executed in the context of a @dfn{test runner}, which is
> +a object that accumulates and reports test results.  This
> specification

Typo: a object -> an object

(this might also be a good change/PR for srfi 64 itself ⇒ upstream)

> +defines how to create and use custom test runners, but implementations
> +should also provide a default test runner.  It is suggested (but not

Does Guile provide a default test runner?
⇒ that may be good to note instead of "should also".

> +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.
…
> +For testing approximate equality of inexact reals
> +we can use @code{test-approximate}:
> +
> +@deffn {Scheme Syntax} test-approximate [test-name] expected test-expr error
> +
> +This is equivalent to (except that each argument is only evaluated
> +once):
> +
> +@lisp
> +(test-assert [test-name]
> +  (and (>= test-expr (- expected error))
> +       (<= test-expr (+ expected error))))
> +@end lisp
> +@end deffn

It would be nice to have an explicit example here.

> +@lisp
> +(test-error #t (vector-ref '#(1 2) 9))
> +@end lisp
> +
> +This specification leaves it implementation-defined (or for a future
> +specification) what form @var{test-error} may take, though all
> +implementations must allow @code{#t}.

It would be good to show what Guile accepts instead.

…
> +@lisp
> +;; Kawa-specific example
> +(test-error <java.lang.IndexOutOfBoundsException> (vector-ref '#(1 2) 9))
> +@end lisp

An example with Guile would be good.
> +@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
> +function that takes a test-runner and returns a boolean.  The
> specifier

is *a* one-argument function
(also for upstream)

Aside from these, this patch looks good to me. 
Thank you!

Can you send one more iteration of the patch?

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]