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.

Flexible Nomenclature

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 assert and should nomenclatures as well for those atune to those particular prespectives.

Literate Programming

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 #should_not.

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.

Embedded Specification

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.

Documentation

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.

Current Status

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

RubyGems

The easiest way to get Quarry is via RubyGems.

      $ sudo gem install quarry
      

Tarball

To install manually, you will need to have Ruby Setup installed. You can get that from here. With that in hand download the latest Quarry tarball package from Rubyforge.

Unpack and run sudo setup.rb from within the package folder. For example:

      $ tar -xvzf quarry-0.3.0.tgz
      $ cd quarry-0.3.0
      $ sudo setup.rb
      

Once installed, be sure to check out the documentation.

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.

• Specification

RDoc API Documention

For more a detailed code-oriented understanding of Quarry, the API documention is also available.

Community

User discussions about Quarry are held on the TigerOps mailing list. Once you've signed up there, you can access the list via the Google Group mirror if you prefer.

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

Development is orchistrated via Rubyforge. The site is http://rubyforge.org/projects/quarry.

You can use gitweb to browse the 'quarry' repository.

Anonymous Access

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:

      gitosis@rubyforge.org:quarry.git
      

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.

Development Community

Developer discussions about Quarry are held on the TigerOps mailing list. Once you've signed up there, you can access the list via the Google Group mirror if you prefer.