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
named ggspec
, create a symbolic link to the ggspec
directory inside
any directory in your $GUILE_LOAD_PATH
(Windows: %GUILE_LOAD_PATH%
).
Then, link or copy the ggspec
script to any directory in your $PATH
(Windows: %PATH%
).
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
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 CONTRIBUTING.md
.
$ 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.
See the lib.scm
file for a detailed reference. A brief introduction to
how it works:
-
The
suite
function 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. -
Inside the
suite
function, a group of tests is organised together using thetests
function. Each test is created using thetest
macro. -
After the tests come the options, which are organised together using the
options
function. Each option is created using theoption
function. -
After the options come the setups, which are organised together using the
setups
function. Each setup (which is a symbol name 'bound' to an expression) is created using thesetup
macro. 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
teardowns
function. Each teardown (which is just a set of expressions) is created using theteardown
macro. 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
case the 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 ggspec
test
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
always return 1
:
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]