quarry

= Ruby Quarry

http://quarry.rubyforge.org

== Introduction

Ruby Quarry is a developers testing and debugging suite. It features a literal-programming BDD specification system, and exception based assertion system, and a few other of useful QA tools.

== Features

=== Specifications

Quarry's BDD/TDD system is uniqe in a few ways. First it utilizes Ruby's Execption system to catch Assertions which are defined via assertion functors. Eg.

4.assert == 5

Because 4 != 5, this expression will raise an Assertion exception. Quarry's Specification Runner class is thus just a means of running and capturing these assertions.

While we used TDD teminology in the above example, Quarry supports a range of momenclature to suit the preferences of TDD vs. BDD developers. The abot could just as well been written as:

4.should == 5

or

4.expect == 5

These are effecitvely the same. For the most part the different terms do exactly the same thing. Somtimes though they differ to conform with the TDD vs. BDD prespective they intend to support.

Quarry's Specifications themselves are simple text files --a practice of literal programming.

Example Specification
=====================

Shows that the number 5 does not equal 4.

    5.should! == 4

But in fact equals 5.

    5.should == 5

If we run this specification in verbatim mode the output would be identical (assuming we did not make a typo and the assertions passed). If there were errors or failures, we would see information detaling each.

As you can see, we used Markdown for this spcecification. Almost any format can be used. The only neccesary distinction is that desciption text be align to the left margin and all specification code be indented. Quarry also recognized headers, currently Markdown and RDoc style headers, which covers most markup foramts in common use today. While strictly speaking Qaurry does not need to recognize headers, it does improve console output a bit if it does.

Give this design some though. It should become clear that this approach if especially fruitful in that it allows documentation and specification to seemlessly merge.

=== Stubs, Mocks and Spies

Quarry provides a flexible stubbing and mocking facility.

For now see RDoc API.

The Spy/Probe (aka the Duck Hunter) can dip-down into a method and provide a read-out how it functions --known as a method signature. Probe is somewhat expiremental becuase it is runtime bound, so proper execution can not be 100% guarenteed. It can miss some parts of a method due to conditional branching (a probe can't pretend to be false) and, albiet rare, it can also get stuck in an infinite loop a la the Halting Problem. Even so, it can be used effectively under controlled situations if used with care.

== Copying

Copyright (c) 2007, 2008 Tiger Ops / Thomas Sawyer

Quarry is distributed under the terms of the GPLv3.