njonsson / trapeze

== Introduction

Writing bug-free code is very difficult. Some of the difficulty can be mitigated
through the use of automated tests or executable specifications which can give
programmers reasons for confidence in the code they write. With automated tests
or executable specifications, the programmer expresses his intent twice -- once
in the code itself and once in the tests or specs. Without a double-check of
programmer intent, it is easy for defects to creep into a program undetected.

Programs written in statically-typed languages are hard enough to get right. Any
programmer worth her salt knows that just because her code compiles cleanly
doesn't mean that it works. An interpreted, dynamically-typed language like Ruby
compounds the problem for programmers who don't make use of automated tests or
executable specifications. There are more degrees of freedom in Ruby code and
therefore more dark places for bugs to hide.

So automated tests and executable specifications are good things. <i>But lots of
code doesn't have test cases or specs.</i> In many cases, code that has them is
inadequately covered. This is a sad reality.

What to do? Wouldn't it be nice if you could have test cases generated for you
automatically? At least then you would have a guard against regression when you
make changes to a program.

== About Trapeze

Enter Trapeze, the safety-net generator for Ruby.

Trapeze generates a suite of unit tests or specifications for existing Ruby
source code. This is accomplished through dynamic analysis, by reflecting on the
public interfaces of classes, modules and top-level methods defined in the
source. Trapeze then exercises each object, module and method, recording the
behavior of the code. This recorded behavior is captured in a suite of test
cases or specifications that can be rendered as test code or executable
specifications.

There is a built-in suite renderer for the Test::Unit library. Other tools such
as the RSpec library and Jay Fields's Expectations library may be supported also
at some future time.

In essence, Trapeze is a tool for characterizing Ruby source code. Trapeze lets
you fly high as you maintain and enhance a Ruby codebase that lacks test or spec
coverage, knowing that you have a regression safety net underneath you.

<b>Trapeze is a pre-alpha product.</b> Multiple major features are not yet ready
for prime time. Stay tuned.

== How to install Trapeze

Trapeze is packaged as a RubyGem. You will need the RubyGems tool installed in
order to take advantage of a one-step installation procedure. With RubyGems
installed, type the following:

  gem install --source http://trapeze.rubyforge.org trapeze

If the installation is successful, you should have the latest version of Trapeze
installed on your system, and along with it, the <tt>trp</tt> command in your
path.

== How to use Trapeze

Trapeze does just one thing: generate a suite of test cases for a given Ruby
codebase. After you generate the suite you can run it.

=== Generate a suite

From the root of your Ruby project, type:

  trp

This will search for files matching the pattern <i>lib/**/*.rb</i> and generate
a safety-net suite in the directory <i>test/trapeze</i>.

Type <tt>trp -h</tt> to learn about available options, including how to search
for source code files matching a different pattern and how to generate a suite
in a different output directory.

=== Run the suite

Find the file named <i>SUITE.rb</i> which is located in the generated output
directory. (By default this directory is <i>test/trapeze</i>.)

Execute this file: <tt>ruby SUITE.rb</tt>.

== Credits

Authored by Nils Jonsson (nils@alumni.rice.edu). Released under the MIT License.

== To do

* Build a system test coverage Rake task that leverages the _aggregate_ option
  of RCov to aggregate the results of all the system tests
* Search classes and modules recursively for nested classes and modules
* Assert the values of user-defined constants and the superclasses of classes
* Add support for --verbose/-v command-line option
* Add support for thrown symbols and raised errors in addition to returned
  objects
* Create mocks and stubs of core- and standard-library IO classes in order to
  make the generated suite more "unit-ish"
* Add support for excluding source code files and method name patterns from
  scanning, since the engine executes code in order to inspect it
* Address the elephant-in-the-room question of code execution paths and how to
  get predictable code coverage in generated tests -- create an alternative
  implementation of Trapeze::Probe that leverages the ParseTree gem