=begin rdoc

== Summary
Quicktest - A utility for inlining ruby unit tests with the ruby code under test

== Example
run with bin/quickspec

=end rdoc

  class Foo
    def initialize
      @bar = true
    end
    def quicktest
      it "bar should be initialized to true" do
        @bar.should == true
      end
    end

    def self.hello arg
      "hello" + arg
    end
    def self.quicktest meth
      it "should prepend 'hello' to its argument" do
        meth["world"].should == 'hello world' # error - no space 'helloworld'
      end
    end
  end

=begin rdoc

Running quicktest on the source of this README file outputs the following:
  .F

  1)
  'Foo hello should prepend 'hello' to its argument' FAILED
  expected: "hello world",
       got: "helloworld" (using ==)
  ./README:22:in `quicktest'
  /home/greg/quicktest/lib/quicktest.rb:65:in `instance_eval'
  /home/greg/quicktest/lib/quicktest.rb:65:in `run_tests'

  Finished in 0.008338 seconds

  2 examples, 1 failure

== Usage
=== Install

  gem install quicktest

=== test code
To test a method, place another method called 'quicktest' immediately after it
the quicktest method has one OPTIONAL argument:
- a method object for the method under test

=== execution
run with

  spec -r quicktest file_to_test

There is a convenience script so that you can just run

  quickspec file_to_test

== Author and License
Copyright (c) 2008 Greg Weber, http://gregweber.info
Licensed under the MIT license

== About

The typical test driven development workflow requires constant switching between the file containg the source code and 
the the file containg the tests. When creating code, it is much faster to be able to place tests immediately after the 
code you are writing.  After the code has been written, it may be a good idea to move it to another file.

Quicktest is designed to support quick tests in a framework agnostic way.  Currently, only an rspec testrunner is 
available, but it is trivial to write one for another testing framework.

Quicktest uses method tracing to know the method you are testing. By default the output of a failed test will show the 
object and method name.

== Install
gem install quicktest

== Source
=== browser
http://github.com/gregwebs/quicktest/tree/master

=== repository
git clone git://github.com/gregwebs/quicktest.git

== Homepage
http://gregweber.info/projects/quicktest.html

== RDoc documentation
included with the gem

== Important Notes
- def quicktest will instantiate an object for the class you are testing, which gives a convenient referenct to self in 
the quicktest method.  However, it calls new() without any parameters.  If you need parameters for new(), you will have 
to use def self.quicktest and call new() yourself

== Configuration
- when testing module instance methods, the module is included into an anonymous class.  By default, that class inherits 
from Object.  To change this you must define an object that the module will be included into by defining the following 
in the module:

  def self.quicktest_include_into; String end

- you can change the testing method name from quicktest to something else using the command line option

  --quicktest better_testing_name

== TroubleShooting
- quicktest methods not working properly? if the class (or one of its ancestors) is overriding method tracing then 
including QuickTest::Tracer will fix it, but you should also fix the class or its ancestor.

== Unimportant Notes
=== production performance
leaving test code in with your production code is not necessarily a good idea, but you can put

  remove_method :quicktest

at the bottom of a class to completely remove the quicktest method

=== rationals
* tests for scripts
Definitely very useful for one file scripts, or any type of code that does not have a well established project home 
where the tests will be.  You can distribute the tests with script so that anyone who wants to modify it can also modify 
the tests instead of assuming the original author did not write any.
You can have a flow of development where a 'quick and dirty' script becomes well tested.  Here is a shell function that 
tests the file before every run.
  function test_run () { quickspec $1 && $1 }
* documentation
Tests are a form of documentation.  It can be argued that it is better to have all documentation include in the source

* efficient TDD and prototyping
When writing fresh code you now have the possibility to be directly next to the code under test without having to switch 
back and forth between files.  When you are done writing the new code, you can easily pull all the quicktest methods out 
and into a spec file.


=== Origins
Quicktest came out of my dabbling in the D programming language, which allows you to place testing blocks inline with 
your source code
  unittest{
   ...
  }

Normally, these blocks are ignored, but if you compile with a different switch, they are linked in and ran at the 
beginning of your program.
Originally, I made an exact copy of this, but among other things, it requires the placement of a line like
  (def unittest;end) if not defined? unittest
at the beginning of the file.  It would be nice if Ruby had a similar construct built in to the language.

=== implementation
Quicktest uses method tracing to know the method you are testing.  For the object under test, testing methods are 
included into it, and then the test is run.


=end rdoc