= test/spec, a BDD interface for Test::Unit

Copyright (C) 2006, 2007, 2008, 2009  Christian Neukirchen <mailto:chneukirchen@gmail.com>


== What is test/spec?

test/spec layers an RSpec-inspired interface on top of Test::Unit, so
you can mix TDD and BDD (Behavior-Driven Development).

test/spec is a clean-room implementation that maps most kinds of
Test::Unit assertions to a `should'-like syntax.

Consider this Test::Unit test case:

    class TestFoo < Test::Unit::TestCase
      def test_should_bar
        assert_equal 5, 2 + 3
      end
    end
    
In test/spec, it looks like this:
    
    require 'test/spec'
    
    context "Foo" do
      specify "should bar" do
        (2 + 3).should.equal 5
      end
    end

Since test/spec 0.4, you can also use the new RSpec 1.0 style:
    
    require 'test/spec'
    
    describe "Foo" do
      it "should bar" do
        (2 + 3).should.equal 5
      end
    end

test/spec does not include a mocking/stubbing-framework; use whichever
you like to.  test/spec has been tested successfully with FlexMock and
Mocha.

test/spec has no dependencies outside Ruby 1.8.


== Mixing test/spec and test/unit

test/spec and Test::Unit contexts/test cases can be intermixed freely,
run in the same test and live in the same files.  You can just add them
to your Rake::TestTask, too.  test/spec allows you to leverage your
full existing Test::Unit infrastructure.

test/spec does not change Test::Unit with the exception of
monkey-patching Test::Unit::TestSuite to order the test cases before
running them.  (This should not do any harm, but if you know a way
around it, please tell me.)

test/spec adds seven global methods, Object#should, Kernel.context,
Kernel.xcontext, Kernel.shared_context, Kernel.describe,
Kernel.xdescribe, and Kernel.describe_shared.  The Kernel methods are
private.

You can use <tt>assert_*</tt> freely in specify-blocks; Object#should
works in plain Test::Unit test cases, too, but they will not be counted.


== Wrapped assertions

+assert_equal+:: <tt>should.equal</tt>, <tt>should ==</tt>
+assert_not_equal+:: <tt>should.not.equal</tt>, <tt>should.not ==</tt>
+assert_same+:: <tt>should.be</tt>
+assert_not_same+:: <tt>should.not.be</tt>
+assert_nil+:: <tt>should.be.nil</tt>
+assert_not_nil+:: <tt>should.not.be.nil</tt>
+assert_in_delta+:: <tt>should.be.close</tt>
+assert_match+:: <tt>should.match</tt>, <tt>should =~</tt>
+assert_no_match+:: <tt>should.not.match</tt>, <tt>should.not =~</tt>

+assert_instance_of+:: <tt>should.be.an.instance_of</tt>
+assert_kind_of+:: <tt>should.be.a.kind_of</tt>
+assert_respond_to+:: <tt>should.respond_to</tt>
+assert_raise+:: <tt>should.raise</tt>
+assert_nothing_raised+:: <tt>should.not.raise</tt>
+assert_throws+:: <tt>should.throw</tt>
+assert_nothing_thrown+:: <tt>should.not.throw</tt>

+assert_block+:: <tt>should.satisfy</tt>

(+a+, +an+ and +be+ without arguments are optional and no-ops.)


== Additional assertions

These assertions are not included in Test::Unit, but have been added
to test/spec for convenience:

* <tt>should.not.satisfy</tt>
* <tt>should.include</tt>
* <tt>a.should.</tt>_predicate_ (works like <tt>assert
  a.</tt>_predicate_<tt>?</tt>)
* <tt>a.should.be </tt>_operator_ (where _operator_ is one of <tt>></tt>, <tt>>=</tt>, <tt><</tt>, <tt><=</tt> or <tt>===</tt>)
* <tt>should.output</tt> (require test/spec/should-output)

If you write an useful general-purpose assertion, I'd like to hear of
it and may add it to the test/spec distribution.


== Messaging/Blaming

With more complex assertions, it may be helpful to provide a message
to show if the assertion has failed.  This can be done with the
Should#blaming or Should#messaging methods:

    RUBY_VERSION.should.messaging("Ruby too old.").be > "1.8.4"

    (1 + 1).should.blaming("weird math").not.equal 11


== Custom shoulds ("Matchers")

To capture recurring patterns in parts of your specifications, you can
define custom "shoulds" (RSpec calls them "matchers") in your
contexts, or include modules of them:

    context "Numbers"
      class EqualString < Test::Spec::CustomShould
        def matches?(other)
          object == other.to_s
        end
      end
    
      def equal_string(str)
        EqualString.new(str)
      end
    
      specify "should have to_s"
        42.should equal_string("42")
      end
    end

Alternatively, your implementation can define
CustomShould#assumptions, where you can use test/spec assertions
instead of Boolean predicates:

    class EqualString < Test::Spec::CustomShould
      def assumptions(other)
        object.should.equal other.to_s
      end
    end

A CustomShould by default takes one argument, which is placed in
self.object for your convenience.

You can CustomShould#failure_message to provide a better error
message.


== SpecDox and RDox

test/spec adds two additional test runners to Test::Unit, based on the
console runner but with a different output format.

SpecDox, run with <tt>--runner=specdox</tt> (or <tt>-rs</tt>) looks
like RSpec's output:

    should.output
    - works for print
    - works for puts
    - works with readline

RDox, run with <tt>--runner=rdox</tt> (or <tt>-rr</tt>) can be
included for RDoc documentation (e.g. see SPECS):

    == should.output
    * works for print
    * works for puts
    * works with readline

SpecDox and RDox work for Test::Unit too:

    $ ruby -r test/spec test/testunit/test_testresult.rb -rs
    
    Test::Unit::TC_TestResult
    - fault notification
    - passed?
    - result changed notification
    
    Finished in 0.106647 seconds.
    
    3 specifications (30 requirements), 0 failures

Since version 0.4, SpecDox and RDox also notice and count empty
specifications.


== Disabled specifications

Akin to the usual Test::Unit practice, tests quickly can be disabled
by replacing +specify+ with +xspecify+ (or +it+ with +xit+).
test/spec will count the disabled tests when you run it with SpecDox
or RDox.

When you use xspecify/xit, you also can drop the block.  This is
useful for writing specifications that you haven't yet started
implementing.

Complete contexts can be disabled by using +xcontext+/+xdescribe+.


== Setup/Teardown

Setup/Teardown methods are run in this order:

  * before(:all) in order of definition
  * before(:each)/setup in order of definition
  * specify
  * after(:each)/setup in order of definition
  * before(:each)/setup in order of definition
  * specify
  * after(:each)/setup in order of definition
  * ...
  * after(:all) in order of definition

Please note that before(:all) and after(:all) are run in their own
instance, so all instance variables they set are lost(!) and not
visible to other specifications.  They are e.g. useful for setting up
database connections or starting servers.


== Shared contexts

Since version 0.9, you can define shared contexts in test/spec using
shared_context/describe_shared.  These contexts are not executed on
their own, but can be included with it_should_behave_like/behaves_like
in other contexts.  You can use shared contexts to structure suites
with many recurring specifications.


== specrb

Since version 0.2, test/spec features a standalone test runner called
specrb.  specrb is like an extended version of testrb, Test::Unit's
test runner, but has additional options.  It can be used for
plain Test::Unit suites, too.

    $ specrb -a -s -n should.output
    
    should.output
    - works for print
    - works for puts
    - works with readline
    
    Finished in 0.162571 seconds.
    
    3 specifications (6 requirements), 0 failures

Run <tt>specrb --help</tt> for the usage.


== test/spec on Rails

If you want to specify your Rails applications, you can use the third-party
plugin "test/spec on Rails", which can be found at:

  http://svn.techno-weenie.net/projects/plugins/test_spec_on_rails/

It features testing of model validation, redirection, output, HTTP
status, template rendering and URL generation.


== Installing with RubyGems

Since version 0.3, a Gem of test/spec is available.  You can install with:

    gem install test-spec

I also provide a local mirror of the gems (and development snapshots)
at my site:

    gem install test-spec --source http://chneukirchen.org/releases/gems


== History

* September 29th, 2006: First public release 0.1.

* October 18th, 2006: Second public release 0.2.
  * Better, module-based implementation
  * Official support for FlexMock and Mocha
  * More robust Should#output
  * Should#_operator_
  * Nested contexts
  * Standalone test/spec runner, specrb

* January 24th, 2007: Third public release 0.3.
  * should.be_close, should.be_an_instance_of, should.be_a_kind_of,
    and should.be_nil have been deprecated.  Use the dot-variants of
    them.  These assertions will be removed in 1.0.
  * specrb -a now includes -Ilib by default for easier out-of-the-box
    testing.
  * Added custom shoulds.
  * Added messaging/blaming.
  * Added disabling of specifications.
  * Small bug fixes.
  * Gem available.

* June 29th, 2007: Fourth public release 0.4.
  * Support for Ruby 1.8.6.
  * Support describe/it/before/after RSpec 1.0 syntax.
  * Allow should.raise { code_that_raises }
  * Add xcontext to disable complete contexts.
  * Backtraces are cleaner now.
  * Mention test/spec on Rails.
  * Fix small Gem bugs.
  * Fix bug related to counting negated assertions.
  * Fix bug in specrb.
  * Allow empty xspecifys.
  * Make SpecDox and RDox count empty specifications.
  * Allow Kernel#context to take a superclass.

* July 2nd, 2008: Fifth public release 0.9.
  * Allow should.<predicate>? as well as should.<predicate>.
  * Add shared contexts.
  * Nested contexts now run the
    setups/teardowns/before(:all)/after(:all) of their parents.

* February 1st, 2009: Sixth public release 0.10.
  * Support for Ruby 1.9.  Now requires the test-spec gem.


== Contact

Please mail bugs, suggestions and patches to
<mailto:chneukirchen@gmail.com>.

Darcs repository ("darcs send" is welcome for patches):
http://chneukirchen.org/repos/testspec


== Thanks to

* Eero Saynatkari for writing <tt>should.output</tt>.
* Tuxie for writing test/spec on Rails.
* Brian Donovan for allowing alternative superclasses.
* Xavier Shay for implementing nested setups/teardowns.
* Chris Wanstrath for <tt>should.raise</tt> with a block and <tt>xcontext</tt>.
* Jean-Michel Garnier for packaging the first gem.
* Mikko Lehtonen, Jan Wikholm, Matt Mower and Michael Fellinger for
  testing the gem.
* Chris McGrath for reporting a bug.
* Thomas Fuchs for script.aculo.us BDD testing which convinced me.
* Dave Astels for BDD.
* The RSpec team for API inspiration.
* Nathaniel Talbott for Test::Unit.


== Copying

Copyright (C) 2006, 2007, 2008, 2009  Christian Neukirchen <http://purl.org/net/chneukirchen>

test/spec is licensed under the same terms as Ruby itself.

Please mail bugs, feature requests or patches to the mail addresses
found above or use IRC[irc://freenode.net/#ruby-lang] to contact the
developer.


== Links

Behavior-Driven Development:: <http://behaviour-driven.org/>
RSpec:: <http://rspec.rubyforge.org/>
script.aculo.us testing:: <http://mir.aculo.us/articles/2006/08/29/bdd-style-javascript-testing>

FlexMock:: <http://onestepback.org/software/flexmock/>
Mocha:: <http://mocha.rubyforge.org/>

Christian Neukirchen:: <http://chneukirchen.org/>