ggspec - lightweight unit testing library for Guile
Copyright (c) 2014 Yawar Amin
GitHub, Reddit, Twitter: yawaramin
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
ggspec is a very lightweight unit testing framework for Guile. Currently I am targeting Guile 1.8. I may port it to other Schemes in future; in principle it should be fairly simple because it doesn't use very many Guile-specific features.
ggspec is self-testing. In fact, it was bootstrapped by the tests--the tests were written first, before there was a unit testing framework to run them; and then the framework was written around the tests.
Assuming you have cloned the
ggspec repository to a directory also
ggspec, create a symbolic link to the
ggspec directory inside
any directory in your
Then, link or copy the
ggspec script to any directory in your
E.g., if you have
~/guile in your Guile load path,
~/bin in your
path, and have cloned the repo into
~/code/ggspec, then run:
cd ~/guile ln -s ~/code/ggspec cd ~/bin ln -s ~/code/ggspec/ggspec
Verifying the framework itself
As I described earlier, the
ggspec framework is tested using itself.
You can run the tests:
cd ~/code/ggspec ./ggspec # Or if you copied/linked the script to a dir in your path, # just ggspec.
See the file
Minimal complete example
$ guile guile> (use-modules (ggspec lib)) guile> (suite "Hello ggspec" end) Suite: Hello ggspec (0 0 0)
The last line above shows the number of passing tests, failing tests, and skipped tests. Since we didn't write any tests here, all three are zero.
lib.scm file for a detailed reference. A brief introduction to
how it works:
suitefunction is presented as the way to organise everything. This includes tests, any options you want to pass in to those tests, any setup variables you want to define before running each test in the suite, and any teardowns you want to do after running each test.
suitefunction, a group of tests is organised together using the
testsfunction. Each test is created using the
After the tests come the options, which are organised together using the
optionsfunction. Each option is created using the
After the options come the setups, which are organised together using the
setupsfunction. Each setup (which is a symbol name 'bound' to an expression) is created using the
setupmacro. Each setup will be re-evaluated before each test is run. So generally you don't want to put expensive computations in these.
After the setups come the teardowns, which are organised together using the
teardownsfunction. Each teardown (which is just a set of expressions) is created using the
teardownmacro. Each teardown will be re-evaluated after each test is run to ensure a clean 'environment' for the next test run.
Options and setups are not required, but since setups come after
options, you have to specify options if you want to specify setups. You
can specify empty (or missing) options, setups, and teardowns, in which
suite function doesn't try to do anything with them.
Normally you will put all your test source code files in a subdirectory
of your project directory called
spec. This lets the
runner find and run all of them.
A short tutorial (in the context of Test-Driven Development):
Suppose we want to develop a function
sqr that should return the
square of its argument (a number). In this example I will show the
function and its test suite together, but usually you would have them in
separate files. For this example you can follow along by making the
changes in your editor and re-loading the source code file in your REPL:
guile> (load "test.scm")
First you write a failing test:
(use-modules (ggspec lib)) (suite "The sqr function" (tests (test "Should square 1 correctly" ;; The 'e' argument below represents (and contains) all the ;; state that we're passing in to the test. All setups, options, ;; etc. e (assert-equal 1 (sqr 1)))))
This suite will fail because the
sqr function does not exist:
Suite: The sqr function ERROR: Unbound variable: sqr
Now implement it to make the test pass:
(define (sqr x) 1)
The test will now pass because we have 'cheated' to make it so:
Suite: The sqr function [PASS]
Note that the output is minimal when a test passes. Now we extend the suite to another 'example':
(use-modules (ggspec lib)) (suite "The sqr function" (tests (test "Should square 1 correctly" e (assert-equal 1 (sqr 1))) (test "Should square 2 correctly" e (assert-equal 4 (sqr 2)))))
This will now fail, again, because the
sqr function is hard-coded to
Suite: The sqr function [PASS] [FAIL] Should square 2 correctly Expected: 4 Got: 1
Now we fix that:
(define (sqr x) (* x x))
This time the test will pass because
sqr handles the general case:
Suite: The sqr function [PASS] [PASS]