-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
141 lines (101 loc) · 4.73 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
spec-check
Copyright (c) Robert Feldt. All rights reserved.
The use and distribution terms for this software are covered by the
Common Public License 1.0 (http://opensource.org/licenses/cpl.php)
which can be found in the file CPL.TXT at the root of this distribution.
By using this software in any fashion, you are agreeing to be bound by
the terms of this license.
You must not remove this notice, or any other, from this software.
spec-check - Specification & checking of software behavior expectations
=======================================================================
Author: Robert Feldt
Email: robert.feldt (at) gmail.com
Version: 0.2
Date:
License: Common Public License
## What is it?
spec-check is a small Clojure library for specifying expectations on
the behavior of software/code and then checking these expectations.
It has similarities with the xUnit family of unit testing frameworks
but is more in the spirit of the recent Behavior-Driven specification
frameworks like RSpec. It extends on both of these styles by adding
higher-order checking capabilities like random (à la Quickcheck and
implemented in Lisp in Clickcheck) and exhaustive testing (à la Smallcheck).
Links:
http://en.wikipedia.org/wiki/XUnit
http://rspec.info/
http://www.cs.chalmers.se/~rjmh/QuickCheck/
http://www.accesscom.com/~darius/software/clickcheck.html
http://www.cs.york.ac.uk/fp/darcs/smallcheck/README
http://www-users.cs.york.ac.uk/~mfn/lazysmallcheck/
## How can I use it?
Here is a small example of how to use spec-check:
(load-file "spec-check.clj")
(clojure/refer 'spec)
; Collect specifications in normal Clojure functions
(defn spec-myspec []
(spec "My first spec"
(is == 1 1)
(is not= 4 (+ 3 1)) ; should fail!
(isnt == 1 2)
(is true? (= 'a 'a))
(isnt true? (== 1 (count [1]))) ; should fail!
))
; and check it
(check (spec-myspec))
if you save that in a file myspec.clj and run it you get:
.F..F
FAILURE:
the code was: (is not= 4 (+ 3 1)), but
arguments *ARE* the same: 4 4
FAILURE:
the code was: (isnt true? (== 1 (count [1]))), but
arguments was: true
Finished in 0.002633 seconds
5 expectations checked, 2 failed
## Where can I get it?
If you have git you can simply
git clone git://github.com/robertfeldt/spec-check.git
or you can get a tarball of the latest repo version from
http://github.com/robertfeldt/spec-check/tarball/master
To write your own specs you only need to get the latest stable
version of the spec-check.clj file here:
http://github.com/robertfeldt/spec-check/tree/master/latest_stable/spec-check.clj?raw=true
## Where can I find more examples?
Check the samples directory, especially factorial\_spec.clj
(which shows parameterized specs) and clojure/nums\_spec.clj
(the start of a spec for Clojures Nums).
## What is the current status?
Done:
* Core with expectations, specs and checking
* Added utility macro isnt which is complement to is
* Stack of spec descriptions updated and then used when reporting failures
* Extend so can be run from command-line to load several specs and run them
together.
Todo:
* Random testing via generator functions
* Add more self-checks in specs/spec-check_spec.clj
* Reporting of line numbers where expectation failed?
* Exhaustive testing (via lazy collections)
* Verbose output formats to get lists of example uses from specs
* Add more specs for Clojure's core funcitonality
Possible Todos / Ideas:
* filters on lazy collections in for-all?
* Add all-are macro to check multiple forms in one go?
* Start with GUI's from the command line. Example commands:
* bar spec-re (fires up a Swing progressbar and shows red/green progress)
* autocheck cljfiles-re & (sits in background and re-runs specs whenever there is a file change)
* Produce html files showing examples, can they tie into the API docs format?
* Allow specs to be added as :spec tag to function metadata and use that when checking.
* weighted-choice chooses randomly according to weights among collections
## Isn't this just a unit testing framework?
I think it is important which words we use and "specifying behavior" is
more in line with what we ultimately want than "testing units". However,
it is perfectly fine to do unit-level code testing in the style of
xUnit in spec-check. In fact, that is how it will often be used.
## Why are the self checks in the specs dir?
I suggest that it is a good idea to separate spec files from the actual code.
One possible convention could be that all spec files are collected in a
specs dir.
They are not in the sample dir since they are primarily specs and not samples
of how to use spec-check.