From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Maxim Cournoyer Newsgroups: gmane.lisp.guile.bugs Subject: bug#71300: [PATCH v3] doc: Document SRFI 64. Date: Mon, 23 Dec 2024 13:48:52 +0900 Message-ID: <87ed1zvwaz.fsf@gmail.com> References: <20240601021743.808-1-maxim.cournoyer@gmail.com> <20240915042603.8529-1-maxim.cournoyer@gmail.com> <87frps2dx7.fsf_-_@web.de> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="40868"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 71300@debbugs.gnu.org, Ludovic =?UTF-8?Q?Court=C3=A8s?= To: "Dr. Arne Babenhauserheide" Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Mon Dec 23 05:51:36 2024 Return-path: Envelope-to: guile-bugs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tPaPn-000AVc-Rk for guile-bugs@m.gmane-mx.org; Mon, 23 Dec 2024 05:51:36 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tPaPJ-0005kO-Ae; Sun, 22 Dec 2024 23:51:05 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tPaPH-0005jr-5x for bug-guile@gnu.org; Sun, 22 Dec 2024 23:51:03 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tPaPG-0005hi-T6 for bug-guile@gnu.org; Sun, 22 Dec 2024 23:51:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:Date:References:In-Reply-To:From:To:Subject; bh=YfeWDNISDvc7UZTZt5f3Uyaf4JDb5hEgkzhtOyqOvoQ=; b=ZoIgJWz+LPPh1A7UtpHVjS6dnEaQkvljx87lTWNVMANvkW8leeSjnSQKycWrFBw0R3ex980yZwqoqCCXyCoZUM76ETkFXaQF8exg0qj5S3fdhNy9xPhPMFpZ2qsIfhBHcNCHP6cc3RNkPVmYp6S7gll/tPsqALzB3SI8mbiGqiq2wE+X0vrzAI+Y4oTQPLbzlJHn3r2I/8M8dXuf8uEH7e6o51j1lle/LNXiTCuy5jZlTXUyxmhpuuNwGXPB42ZpJ5+CQiqcDXs0szp1piI44SPRZ4/nsxk4EIhT4D1q/6X/MWuJkHg0+Wx/+yFqWGGbt3VnVeWtjl/iHpY/8KXXjA==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tPaPG-0005pQ-Hk for bug-guile@gnu.org; Sun, 22 Dec 2024 23:51:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Mon, 23 Dec 2024 04:51:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 71300 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Original-Received: via spool by 71300-submit@debbugs.gnu.org id=B71300.173492941322076 (code B ref 71300); Mon, 23 Dec 2024 04:51:02 +0000 Original-Received: (at 71300) by debbugs.gnu.org; 23 Dec 2024 04:50:13 +0000 Original-Received: from localhost ([127.0.0.1]:52833 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPaOS-0005jY-Df for submit@debbugs.gnu.org; Sun, 22 Dec 2024 23:50:13 -0500 Original-Received: from mail-pl1-f173.google.com ([209.85.214.173]:58869) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tPaOO-0005hx-Ce for 71300@debbugs.gnu.org; Sun, 22 Dec 2024 23:50:10 -0500 Original-Received: by mail-pl1-f173.google.com with SMTP id d9443c01a7336-2165448243fso40075795ad.1 for <71300@debbugs.gnu.org>; Sun, 22 Dec 2024 20:50:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1734929342; x=1735534142; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:user-agent:message-id:date :references:in-reply-to:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=YfeWDNISDvc7UZTZt5f3Uyaf4JDb5hEgkzhtOyqOvoQ=; b=eqgkWOz2Kc4JnfEus6YKV/Y4wXqUIt32jn5lnIFI3GXyOT3IImvgCTvJSVrnc/+eg7 EPBR0QH6drsalW1TcJTjZr1U3TFR74LxQ4AYQfVG1Pxhm4SqthBYLTs+oFZBzwaDR83T pM/rgNjVoxQ9sJ3WGDwSiKmluw0spo0Ef4oZXiVyqbSJuJzfd4DlsBXBSjQsSuGAw8LN kChnsZuA+bGz40BzAOilHRp/eltZSGjE5pAJny5ERk+oW+4/5C3zrrgZIuKCbYPO2+xk 35LG6VmB4yl5K1OVPbo3YIlec5msPRIuOEwxgV/danhQgPvx/gLF4/gcr84GfJdRgAOC gEYQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1734929342; x=1735534142; h=content-transfer-encoding:mime-version:user-agent:message-id:date :references:in-reply-to:subject:cc:to:from:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=YfeWDNISDvc7UZTZt5f3Uyaf4JDb5hEgkzhtOyqOvoQ=; b=g0LXII2wFHVeTYz418UIT+r3ytanROqhQB5hj6CnFnmBxWZZvaZvcN9rLJPO6gvuSr 8r1NcOeJ/0aPTyBfzRS8nMqu1tb3Fyqo4tcZaKCXv86YlTHOXjBVqrO41RSP4WaM2oUw Tv7gwdGtoqR8C82P6db2oOpKv8x8WFSsz+hV7TNBPkgs+OJdxYUAwaYctYph6fHZNADO tPmhJMpOkW/83yivTwyukgUQDq57sFl3ZkOKbYOeBRfpz88OLd3OHlajRaCDeOPYvhcz WRGS4pREAsgWs9Nfy8V6NrwyCBMwSfvRa0kAGiNKKjlJFE24v4BukK9EDxoA93w8HkCd cfAw== X-Gm-Message-State: AOJu0YyZML5D/HtAg8wA6kRuha1sa9mF3RJaSdyl4+0+E+3WvKcWT/9m OSQpfuIYYzywOCb/EeOW6TxQ3w5j3m9IR6SvS1itJrnUFhneJgLe X-Gm-Gg: ASbGncuiceqd/9X67UhZfLSlp+/PXd5mIflL49VfQcxpg+3F8lM4G2Ed68yFqjjTkwA 4e2SOgRKILl3MV8ZvHRkRjhY9UBEF2iKsRRm9P7gL4kn7TETjzpkl+MaE5p768d1dC8a+97T3Uz 1ITfa/BFkr42lAWSpKNOR/5jKAO3AEif/My0iT7dsPKLj+b9JIaGIbycgWzqOwm+LFkp/5PswcX gLPW2djKNXufhTdxB3E5o5+Y3+RHUVucM3T550VSjDLROmPxGB5NA== X-Google-Smtp-Source: AGHT+IFodp5fUe1f7mGpnLDCCnRnt3gxxsr8+S7RBRAVwb1vL5eo1Na81ARCo55A6HMOXb+Zdod3lw== X-Received: by 2002:a17:902:f682:b0:216:6f1e:5799 with SMTP id d9443c01a7336-219e6f14829mr124837425ad.35.1734929342299; Sun, 22 Dec 2024 20:49:02 -0800 (PST) Original-Received: from terra ([2405:6586:be0:0:c8ff:1707:9b9:af89]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-219dc9f5227sm64811475ad.185.2024.12.22.20.49.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 22 Dec 2024 20:49:01 -0800 (PST) In-Reply-To: <87frps2dx7.fsf_-_@web.de> (Arne Babenhauserheide's message of "Sun, 22 Sep 2024 12:14:28 +0200") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.bugs:11135 Archived-At: Hi, Finally acting on this, now that it's already been merged by Ludovic ^^'. "Dr. Arne Babenhauserheide" writes: > Maxim Cournoyer 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. Ludovic kept the current convention, so that's tackled. >> @@ -5290,12 +5291,827 @@ needed to get SRFI-61 itself. Extended @code{c= ond} is documented in > =E2=80=A6 >> +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=E2=80=99d take the racket specific part out. It's relevant to the context in which this SRFI was created. Not critical for Guile, but maybe nice for the reader wanting to know the full story. I don't feel strongly about removing it though. >> +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=E2=80=99t needed here, I think. I turned it into 'but it is hoped', i.e. neutral tone at least. >> +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 =E2=87=92 upstrea= m) Thanks. Fixed, and an upstream PR already submitted for this one and others you found: . >> +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? > =E2=87=92 that may be good to note instead of "should also". I've added to this paragraph documenting what the implementation in Guile does: --8<---------------cut here---------------start------------->8--- modified doc/ref/srfi-modules.texi @@ -5393,7 +5393,25 @@ should also provide a default test runner. It is su= ggested (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 =3D #t +* PASS: +$2 =3D ((pass . 1)) +* PASS: +$3 =3D ((pass . 2)) +* PASS: +$4 =3D ((pass . 3)) +*** Leaving test group: vec-test *** +*** Test suite finished. *** +*** # of expected passes : 3 +@end example + +It also returns the @code{} object. @subsubheading Simple test-cases --8<---------------cut here---------------end--------------->8--- >> +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. > =E2=80=A6 >> +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 (>=3D test-expr (- expected error)) >> + (<=3D test-expr (+ expected error)))) >> +@end lisp >> +@end deffn > > It would be nice to have an explicit example here. > I've added an example: --8<---------------cut here---------------start------------->8--- @@ -5455,6 +5473,14 @@ once): (and (>=3D test-expr (- expected error)) (<=3D test-expr (+ expected error)))) @end lisp + +Here's an example: +@lisp +(test-approximate "is 22/7 within 1% of =CF=80?" + 3.1415926535 + 22/7 + 1/100) +@end lisp @end deffn @subsubheading Tests for catching errors --8<---------------cut here---------------end--------------->8--- >> +@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. I've kept the original text, but appended this paragraph to it: --8<---------------cut here---------------start------------->8--- @@ -5492,6 +5518,23 @@ classes: An implementation that cannot catch exceptions should skip @code{test-error} forms. + +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 @subsubheading Testing syntax --8<---------------cut here---------------end--------------->8--- > =E2=80=A6 >> +@lisp >> +;; Kawa-specific example >> +(test-error (vector-ref '#(1 2) 9= )) >> +@end lisp > > An example with Guile would be good. I've added this: --8<---------------cut here---------------start------------->8--- @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 --8<---------------cut here---------------end--------------->8--- >> +@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) Fixed. > Aside from these, this patch looks good to me. > Thank you! Thank you. As I said, it's been applied already, thanks to Ludovic. I'll try ensure this follow-up also does! --=20 Thanks, Maxim