Forum: Ruby test/spec 0.4, a BDD interface for Test::Unit

Announcement (2017-05-07): is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see and for other Rails- und Ruby-related community platforms.
Christian N. (Guest)
on 2007-06-29 18:06
(Received via mailing list)

today I'm releasing test/spec 0.4, a library to do BDD with Test::Unit.

== News in 0.4:

* 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.

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

In test/spec, it looks like this:

    require 'test/spec'

    context "Foo" do
      specify "should bar" do
        (2 + 3).should.equal 5

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

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

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

== Wrapped assertions

assert_equal: should.equal, should ==
assert_not_equal: should.not.equal, should.not ==

assert_match: should.match, should =~
assert_no_match: should.not.match, should.not =~

assert_respond_to: should.respond_to

assert_raise: should.raise
assert_nothing_raised: should.not.raise
assert_throws: should.throw
assert_nothing_thrown: should.not.throw
assert_block: should.satisfy

== Additional assertions

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

* should.not.satisfy
* a.should.<predicate> (works like assert a.<predicate>?)
* <operator> (where <operator> is <, <=, >, >=, or ===)
* should.output, to check what is printed

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

      def equal_string(str)

      specify "should have to_s"
        42.should equal_string("42")

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

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

== 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 --runner=specdox (or -rs) looks like RSpec's output:

    - works for print
    - works for puts
    - works with readline

RDox, run with --runner=rdox (or -rr) can be included for RDoc

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

    - fault notification
    - passed?
    - result changed notification

    Finished in 0.106647 seconds.

    3 specifications (30 requirements), 0 failures

== test/spec on Rails

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

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

== Thanks to

* Eero S. for writing <tt>should.output</tt>.
* Tuxie for writing test/spec on Rails.
* Brian Donovan for allowing alternative superclasses.
* Chris W. for <tt>should.raise</tt> with a block and
* Jean-Michel Garnier for packaging the first gem.
* Mikko L., Jan Wikholm, Matt M. and Michael F. for
  testing the gem.
* Chris McGrath for reporting a bug.
* Thomas F. for BDD testing which convinced me.
* Dave A. for BDD.
* The RSpec team for API inspiration.
* Nathaniel T. for Test::Unit.

== Copying

Copyright (C) 2006, 2007  Christian N.
test/spec is licensed under the same terms as Ruby itself.

== Where can I get it?

You can download test/spec 0.4 at

Alternatively, you can checkout from the development repository with:

           darcs get

Please mail bugs, suggestions and patches to

(Patches using "darcs send" are most welcome.)

== Installing with RubyGems

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

    gem install test-spec

(It may take some time for the index to be updated and the mirrors
propagated.)  I also provide a local mirror of the gems (and
development snapshots) at my site:

    gem install test-spec --source

== Links

Behavior-Driven Development:: <>
RSpec:: <> testing::
FlexMock:: <>
Mocha:: <>

Happy hacking and have a nice day,
Christian N.

be9a3d747dc212bb21f7d78928d20652  test-spec-0.4.0.tar.gz
e2f4757aa764d67ed5630d5e1093316c  test-spec-0.4.0.gem
James H. (Guest)
on 2007-07-01 11:50
(Received via mailing list)
Thank you very much.  I'm enjoying this : )
This topic is locked and can not be replied to.