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.