Change How You Drive!
Ruby Quarry is a BDD/TDD framework that can frees you of strict nomenclatures, opening up vast reserves in test ore and behavior mining. Quarry uses a literate programming model that elimates the barriers on how to descirbe your specifications and unit tests, leading to a proverbial gold mine in systems documentation.
Quarry's BDD/TDD system is unique in two ways. First, it does not enforce a BDD or TDD perspective, but leaves that choice up to the programmer and the case at hand, by supporting a deversified set of "this-is-so" methods. For instance, the following are all equivalent.
5.expect == 5 5.assert == 5 5.should == 5
Quarry's defacto terminology is
expect becuase it is suitable
to both testers and specifiers. And Quarry full supports
should nomenclatures as well for those atune to those
Secondly, and more importantly, Quarry's sepcifications are an application of literate programming. As such, they are completely free-form. In other words, unlike other BDD/TDD systems, Quarry has no special organization domain langauge. Instead specifications are simply text/markup files (typically RDoc format). For example, a specification may look something like:
= Example Specification Concerning the Number 5, it should not be 4. 5.should! == 4 But it is itself. 5.should == 5
Notice the use of '!' at the end of 'should'. This is read as 'should NOT'. For those
who prefer, the word can be spelled out as
Stubbing, Mocking and Spying
Quarry also provides a flexible test-double facility consiting of stubs, light-weight mocks and spies. These are very flexible tools. For instance, a Qaurry stub can act as a reuable module or automatically via object's singleton class. An example of the later:
obj = "example" obj.stub.literal(1) == "one" obj.stub.literal(2) == "two" obj.literal(1) #=> "one" obj.literal(2) #=> "two"
Quarry actually discourages the use of mocks as they are traditionally understood, becuase they create overly tight coupling between specification and implementation. But Quarry provides light-weight mocks that are in effect pre-asserted stubs.
obj = "example" obj.mock.to_s == "one" obj.to_s #=> Assertion Error
Lastly, a method-probe/test-spy is also under development, which can be used to dip-down into a method and provide a readout of the methods signitures.
Also in the works is an embedded test/spec extraction tool. This allows tests/specs to be embedded in block comments, which can be a very convenient means to provide unit test/specs.
Finally, when all is said and done (ie. your tests/specs pass ;p), good looking documentation can be generated directly from the Quarry markups. Since these files use common markup formats, like RDoc or Markdown, it's easy enough to generate the documentation with your favorite tool or by writting a quick script. Quarry also provides a basic built-in tool to get you started.
Here is an (incomplete) example.
The library is
BETA ware. There are still a few parts of the system
that need to be polished, mostly noteably the built-in documentor. However the system
is stable enough for general use, and has already become the QA system for a few projects.
Download & Install
The easiest way to get Quarry is via RubyGems.
$ sudo gem install quarry
Unpack and run
sudo setup.rb from within the package folder.
$ tar -xvzf quarry-0.3.0.tgz $ cd quarry-0.3.0 $ sudo setup.rb
Once installed, be sure to check out the documentation.
The most amazing thing about Quarry specification is that they can be prefectly renderable markup. To demostrate here are links to the HTML rendered specification for Quarry itself.
RDoc API Documention
For more a detailed code-oriented understanding of Quarry, the API documention is also available.
Tips and Tricks
Quarry's Mocks are not like mocks in other BDD tools. Mocks in other libraries validate that methods return are invoked, how many times they are invoked, and in what order. This creates overly tight coupling between test and code --this is not validating behavior, but implementation. Quarry's mock objects only validate return values. Nothing more. So in effect a mock is stub with post-method assertions built-in.
Development is orchistrated via Rubyforge. The site is http://rubyforge.org/projects/quarry.
You can use gitweb to browse the 'quarry' repository.
To pull the quarry repository anonymously, use:
$ git clone git://rubyforge.org/quarry.git
Developer Access via Gitosis
Registered Developers, the remote setting for the repository is:
If you use Quarry, contributions to it's improvement are very important and will be sung many wonderous praises ;) If you'd like to contribute, please contact us via the Tiger Ops mailing list.