ClojureGiven

Covering ClojureGiven, version 1.1.0.

ClojureGiven is a port of Jim Weirich's rspec-given BDD test framework to Clojure. ClojureGiven is implemented on top of clojure.test through a set of macros that provide a basic Given/When/Then notation.

Download from clojars.org - http://clojars.org/clojure-given

Status

ClojureGiven is ready for production use.

Example

Here is a specification written in the ClojureGiven framework:

Below is the output from "lein test"

Let's talk about the individual statements used in the Given framework.

Given

The Given section specifies a starting point, a set of preconditions that must be true before the code under test is allowed to be run. In standard test frameworks the preconditions are established with a combination of setup methods and code in the test.

In the example code above the preconditions are started with Given statements. A top level Given (that applies to the entire defspec block) says that two preconditions exist for a variable t1 & t2 with some dependent variable of "x".

Note that "x" are not specified in the top level defspec block, but are given in each of the nested contexts. By pushing the definition of "x" into the nested contexts, we can vary it as needed for that particular context.

A precondition in the form "(Given [var ])" creates a lazy accessor that is evaluated when the first reference is encountered. If any variable referenced in the expression the lazy accessor is will re-evaluate at the next reference. If you want a non-lazy given, use "(Given! [var ])".

The preconditions are run in order of definition. Nested contexts will inherit the preconditions from the enclosing context, with out preconditions running before inner preconditions.

When

The When block specifies the code to be tested or specified. After the preconditions in the given section are met, the when code block is run.

There should only be one When block for a given context. However, a When in an outer context should be treated as a Given in an inner context. E.g.

When examples:

The code block is executed once per test and the value of the code block is bound to 'result'.

Then

The Then sections are the postconditions of the specification. These then conditions must be true after the code under test (the When block) is run.

The code in the Then block should be a single assertion. Code in Then blocks should not have any side effects.