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