| Path: | README |
| Last Update: | Wed Jan 24 12:13:27 CET 2007 |
Copyright (C) 2006, 2007 Christian Neukirchen <chneukirchen@gmail.com>
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
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.
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 two global methods, Object#should and Kernel.context.
You can use assert_* freely in specify-blocks; Object#should works in plain Test::Unit test cases, too, but they will not be counted.
| assert_equal: | should.equal, should == |
| assert_not_equal: | should.not.equal, should.not == |
| assert_same: | should.be |
| assert_not_same: | should.not.be |
| assert_nil: | should.be.nil |
| assert_not_nil: | should.not.be.nil |
| assert_in_delta: | should.be.close |
| assert_match: | should.match, should =~ |
| assert_no_match: | should.not.match, should.not =~ |
| assert_instance_of: | should.be.an.instance_of |
| assert_kind_of: | should.be.a.kind_of |
| 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 |
(a, an and be without arguments are optional and no-ops.)
These assertions are not included in Test::Unit, but have been added to test/spec for convenience:
If you write an useful general-purpose assertion, I’d like to hear of it and may add it to the test/spec distribution.
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
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.
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:
should.output
- works for print
- works for puts
- works with readline
RDox, run with —runner=rdox (or -rr) 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
Akin to the usual Test::Unit practice, tests quickly can be disabled by replacing specify with xspecify. test/spec will count the disabled tests when you run it with SpecDox or RDox.
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 specrb —help for the usage.
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
Please mail bugs, suggestions and patches to <chneukirchen@gmail.com>.
Darcs repository ("darcs send" is welcome for patches): chneukirchen.org/repos/testspec
Copyright (C) 2006, 2007 Christian Neukirchen <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 to contact the developer.
| Behavior-Driven Development: | <behaviour-driven.org/> |
| RSpec: | <rspec.rubyforge.org/> |
| script.aculo.us testing: | <mir.aculo.us/articles/2006/08/29/bdd-style-javascript-testing> |
| FlexMock: | <onestepback.org/software/flexmock/> |
| Mocha: | <mocha.rubyforge.org/> |
| Christian Neukirchen: | <chneukirchen.org/> |