From: Arne Babenhauserheide <arne_bab@web.de>
To: guile-user@gnu.org
Subject: Python-style doctests in Guile (implemented, please comment)
Date: Sun, 30 Jul 2017 20:54:14 +0200 [thread overview]
Message-ID: <87379d7m66.fsf@web.de> (raw)
[-- Attachment #1: Type: text/plain, Size: 2774 bytes --]
Hi,
I implemented doctests in Guile which allow writing SRFI-64 tests
directly in the docstring. Here’s a minimal example:
(import (examples doctests))
(define (one)
"(test 'foo
(test-equal 1 (one)))"
1)
(doctests-testmod (current-module))
Writing simple tests directly in the procedure-documentation makes for
very natural test-driven-design which gets extended into basic
documentation automatically: Start the procedure, write a basic test in
the docstring, implement the body till the test passes and finally
create api-docs from the docstrings which then also show basic usage
examples in the tests.
My questions: This method here is the simplest implemenation of this
feature. It would be great if you could comment on it. Is this structure
good? Would you do it differently? Is "(test-equal 1 (one))" close
enough to an example in the REPL, or would it serve for better
usage-examples in another structure?
The output from running the minimal example is plain SRFI-64 output,
though with extended identifiers:
$ ./doctests-testone.scm
%%%% Starting test ._-guile-user--foo--foo (Writing full log to "._-guile-user--foo--foo.log")
# of expected passes 1
$ cat ._-guile-user--foo--foo.log
%%%% Starting test ._-guile-user--foo--foo
Group begin: ._-guile-user--foo--foo
Test begin:
source-line: 2
source-form: (test-equal "bar" (foo))
Test end:
result-kind: pass
actual-value: "bar"
expected-value: "bar"
Group end: ._-guile-user--foo--foo
# of expected passes 1
The syntax for the identifier is:
._-<filename-or-module>--<function name>--<testid>
I mainly know doctests from Python. There they use a special syntax
which looks like the interpreter.
For Guile I rather chose to start the tests with "(test 'testname" and
treat as test everything read by (read).
Avoiding (test-begin 'testname) and (test-end 'testname) makes for
easier parsing. (they are added automatically using the 'testname)
Here’s a somewhat longer example with the test-execution tucked away in
the main file so it does not interfere with importing the module:
<https://bitbucket.org/ArneBab/wisp/src/1ce02fce232f429fc1cbd29c666e36d34ec22d76/examples/doctests-test.scm>
The full code is available in the wisp-repo:
<https://bitbucket.org/ArneBab/wisp/src/1ce02fce232f429fc1cbd29c666e36d34ec22d76/examples/doctests.scm>
(The code is originally written in wisp, but I decided to use
parenthizes syntax nontheless, because using s-exps makes for more
obvious parsing)
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]
next reply other threads:[~2017-07-30 18:54 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-07-30 18:54 Arne Babenhauserheide [this message]
2017-07-31 8:22 ` Python-style doctests in Guile (implemented, please comment) Chaos Eternal
2017-07-31 17:44 ` Arne Babenhauserheide
2017-08-01 1:36 ` Chaos Eternal
2017-07-31 12:51 ` Mark H Weaver
2017-07-31 13:04 ` Panicz Maciej Godek
2017-07-31 17:23 ` Arne Babenhauserheide
2017-08-01 22:04 ` Vítor De Araújo
2017-10-10 18:21 ` Arne Babenhauserheide
2017-10-10 22:40 ` Vítor De Araújo
2017-10-14 13:05 ` Arne Babenhauserheide
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87379d7m66.fsf@web.de \
--to=arne_bab@web.de \
--cc=guile-user@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).