Change How You Drive!

Quarry is a smart, easy to use, file scaffolding system. It can generate a large variety of layouts, from a traditional Ruby project to common website starter setups.

Quarry is pluggable. New "mines" are easy to create with templates based on eRuby, and easily distributable via SCM or Gem package.

Ruby Quarry is a framework for Literate Driven Development (LDD).^* Literate Driven Development is a superset of Test Driven Development (TDD) and Behavior Driven Development (BDD). Unlike TDD which begins with executable tests to verify behavior, and BDD which goes a step further by providing developer-oriented outlines of these behaviors, LDD takes the final step of having the developer write actual requirements documentation for systems behavior.

While this means the developer must take time to write descriptions of behavior, it in turn frees the developer of strict nomenclatures and specification patterns. Quarry uses a literate programming system that elimates the barriers on how to descirbe your behavior specifications and unit tests, leading to a proverbial gold mine in systems documentation.

Ruby Quarry is an easy-to-use tool that lets end-users read and help create requirements that developers can build from and run as acceptance tests.

LDD has several big advantages over other programming strategies, especially:

• Keeps you from over-designing/complicating things (If you can't explain them, don't use them)
• Gives you the chance to get your ideas peer-reviewed since it helps people to understand what you are trying to do.
• Good Documentation - If you use LDD your project will always be very well documented.
• Helps Planning - If Users know how things are going to work in future they can fine tune their projects to be future-safe.
• Creates user-friendly software - If the developer writes the documentation for the user he'll think more like him and make software that is user-oriented.
• Keeps up motivation - Believe it or not, writing the documentation for things you did and that you will do can be a motivationally rewarding experience.

^* Literate Driven Development is sometimes called Documentation Drive Development (DDD), but we use the term literate to differentiate it from Domain Driven Design (DDD), and furthermore to drive home that it is a form of Literate Programming.

Literate Programming

Quarry specifications are an application of Literate Programming. As such, they are completely free-form. In other words, unlike other systems, Quarry has no special organization domain langauge. Instead, specifications are simply text/markup files (typically RDoc's SimpleMarkup format). For example, a specification may look like this.

      = 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.)

As you can see there are no "context", "describe" or "it" calls. There is only the clean description of what is to be specified and demonstrated.

Flexible Assertion Nomenclature

Like TDD or BBD, LDD also needs means of making assertions. Quarry's does not enforce a behavior-focused or test-focused nomeclature, but largely leaves it to the developer and the case at hand. By supporting a more deversified set of "say-it-is-so" methods, Quarry maximizes the descriptive suitability to the real requirements. For example, the following statements are all equally supported and logically equivalent.

        5.expect == 5
        5.assert == 5
        5.should == 5
      

Each of these methods operate uniformly as functors, but vary in their other uses according to the their respective concepts. For instance expect can be used to specify an error will be raised.

        expect NoMethodError do
          what?
        end
      

While blocks to assert ensure truth.

        assert do
          4 == 4
        end
      

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 test spy, or method probe, is also under development, which can be used to dip-down into a method and provide a readout of the methods signatures.

Documentation Generation

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 simple built-in tool to get you started. Here is an example.

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. Then download the latest Quarry tarball from Rubyforge. And unpack and run sudo setup.rb from within the package folder. For example:

      $ tar -xvzf quarry-0.5.0.tgz
      $ cd quarry-0.5.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.

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.