I like to write tests in a specification based fashion. So I started to work on Guile-Spec.

At the time of writing this post, it's no more than a set of syntax-rules on top of SRFI-64.

Let's see how it feels…

Introductory tutorial

Let's say I want to make sure I understand correctly the Guile API for lists.

One basic test

Here is a minimal program, with a Guile-Spec test suite, where I ensure the empty list is the empty list (you can never be too careful) :

(use-modules (spec))

(install-spec-runner-term)

(describe "Guile API - Lists"
  (it "is null"
    (should (null? '()))))

It will produces the following ouput when interpreted :

$ guile --no-auto-compile t.scm
Guile API - Lists
    PASS is null

The test suite wants to be read as a conversation. The describe form lets you tell what you are testing. It will contains your spec units (at least one) like the it form which contains the assertion (here a should form which accepts an expression that evaluates to a boolean).

Hack on!

You can try this example and hack on it ! You can try another predicate (i.e. list?) or another list (i.e. '(1 2 3), maybe something more sophisticated) or change the names, etc. And see what happens !

Troubleshoting

You might encounter errors while hacking. Here are a few list with mighty reasons :

• This error tells you Guile-Spec is not installed on your system or is not it the GUILE_LOAD_PATH.

ice-9/boot-9.scm:3329:6: In procedure resolve-interface:
no code for module (spec)

• This error tells you the it form is invalid. It should contain only one should.

ice-9/boot-9.scm:1685:16: In procedure raise-exception:
Syntax error:
unknown file:66:6: source expression failed to match any pattern in form (it "should not be false" (should-not #f) (should-not #f))

• This error tells you (implicitely) the describe form is missing :

ice-9/boot-9.scm:1685:16: In procedure raise-exception:
test-runner not initialized - test-begin missing?

• This is not an error but the indication that you forget to install the test runner from Guile-Spec :

%%%% Starting test Guile API - Lists  (Writing full log to "Guile API - Lists.log")
# of expected passes      1

Two tidy tests

I want to continue to challenge my understanding of the Guile API (or do I want to challenge the Guile API?). So I'm gonna add a test and explicit the common context between the two tests.

(use-modules (spec))

(install-spec-runner-term)

(describe "Guile API - Lists"
  (context "the empty list"
    (it "is null"
      (should (null? '())))
    (it "is a list"
      (should (list? '())))))

It will produces the following ouput when interpreted :

$ guile --no-auto-compile t.scm
Guile API - Lists
- the empty list
     PASS is null
     PASS is a list

Thank you very much for reading this article!

Don't hesitate to give me your opinion, suggest an idea for improvement, report an error, or ask a question ! I would be so glad to discuss about the topic covered here with you ! You can reach me here.

Don't miss out on the next ones !

And more importantly, share this blog and tell your friends it's the best blog in the history of Free Software! No kidding!

#gnu #guile #tdd #guilespec #tutorial #english