Lapidary Design Overview

        by Nathaniel Talbott

I'd suggest starting with Kent Beck's design documentation for Smalltalk Unit (the granddaddy of all the 'xunits'), on which I've based my design. Even if you don't know Smalltalk, this is probably the best place to start, since Kent Beck's both a better writer and a better programmer than I am; it's definitely worth skimming the Smalltalk (or you could learn Smalltalk; I promise it will improve your Ruby code :-)).

Now that you've read that, here are each of the core classes in Lapidary along with a quick one-liner about what their responsibilities include. Someday I'll get around to drawing a diagram or something. Note that this is the design document; you should check out the usage document if you just want to know how to use Lapidary.

Framework classes and modules

• Lapidary::Assertions

  A module containing all of the standard Lapidary assertions. Mixed in to TestCase. Anything implementing addFailedAssertion() and addSuccessfulAssertion() can mix it in and assert things. Of course, you'll also need to catch the :assertionFailed signal somewhere, as it gets thrown if/when an assertion fails.

• Lapidary::Error

  Encapsulates an error in a test. Created by TestCase when it rescues an exception thrown during the processing of a test.

• Lapidary::Failure

  Encapsulates a test failure. Created by TestCase when it catches the :assertionFailed signal coming during the processing of a test.

• Lapidary::TestCase

  Ties everything together. If you subclass and add your own test* methods, it takes care of making them into tests and wrapping those tests into a suite. It also does the nitty-gritty of actually running an individual test and collecting its results into a TestResult object.

• Lapidary::TestResult

  Collects Failures and Errors so that they can be displayed to the user. To this end, observers can be added to it, allowing the dynamic updating of, say, a UI.

• Lapidary::TestSuite

  A collection of tests which can be run(). Note: It is easy to confuse a TestSuite instance with something that has a static suite() method; I know because I have trouble keeping them straight. Think of something that has a suite() method as simply providing a way to get a meaningful TestSuite instance.

Runner classes

• Lapidary::UI::TestRunnerMediator

  Provides an interface to write any given UI against, hopefully making it easy to write new UIs.

• Lapidary::UI::Console::TestRunner

  Runs a TestSuite on the console.

• Lapidary::UI::GTK::TestRunner

  Runs a TestSuite in a Gtk UI. Obviously, this one requires you to have Gtk and the Ruby Gtk extension installed.