Bacon – small RSpec clone.¶ ↑

"Truth will sooner come out from error than from confusion."
                                            ---Francis Bacon

Bacon is a small RSpec clone weighing less than 350 LoC but nevertheless providing all essential features.

Whirl-wind tour¶ ↑

require 'bacon'

describe 'A new array' do
  before do
    @ary = Array.new
  end

  it 'should be empty' do
    @ary.should.be.empty
    @ary.should.not.include 1
  end

  it 'should have zero size' do
    @ary.size.should.equal 0
    @ary.size.should.be.close 0.1, 0.5
  end

  it 'should raise on trying fetch any index' do
    lambda { @ary.fetch 0 }.
      should.raise(IndexError).
      message.should.match(/out of array/)

    # Alternatively:
    should.raise(IndexError) { @ary.fetch 0 }
  end

  it 'should have an object identity' do
    @ary.should.not.be.same_as Array.new
  end

  # Custom assertions are trivial to do, they are lambdas returning a
  # boolean vale:
  palindrome = lambda { |obj| obj == obj.reverse }
  it 'should be a palindrome' do
    @ary.should.be.a palindrome
  end

  it 'should have super powers' do
    should.flunk "no super powers found"
  end
end

Now run it:

$ bacon whirlwind.rb
A new array
- should be empty
- should have zero size
- should raise on trying fetch any index
- should have an object identity
- should be a palindrome
- should have super powers [FAILED]

Bacon::Error: no super powers found
	./whirlwind.rb:39: A new array - should have super powers
	./whirlwind.rb:38
	./whirlwind.rb:3

6 specifications (9 requirements), 1 failures, 0 errors

If you want shorter output, use the Test::Unit format:

$ bacon -q whirlwind.rb
.....F
Bacon::Error: no super powers found
	./whirlwind.rb:39: A new array - should have super powers
	./whirlwind.rb:38
	./whirlwind.rb:3

6 tests, 9 assertions, 1 failures, 0 errors

It also supports TAP:

$ bacon -p whirlwind.rb
ok 1        - should be empty
ok 2        - should have zero size
ok 3        - should raise on trying fetch any index
ok 4        - should have an object identity
ok 5        - should be a palindrome
not ok 6    - should have super powers: FAILED
# Bacon::Error: no super powers found
# 	./whirlwind.rb:39: A new array - should have super powers
# 	./whirlwind.rb:38
# 	./whirlwind.rb:3
1..6
# 6 tests, 9 assertions, 1 failures, 0 errors

$ bacon -p whirlwind.rb | taptap -q
Tests took 0.00 seconds.
FAILED tests 6
   6) should have super powers: FAILED

Failed 1/6 tests, 83.33% okay.

(taptap is available from chneukirchen.org/repos/taptap/)

As of Bacon 1.1, it also supports Knock:

$ bacon -k whirlwind.rb
ok - should be empty
ok - should have zero size
ok - should raise on trying fetch any index
ok - should have an object identity
ok - should be a palindrome
not ok - should have super powers: FAILED
# Bacon::Error: no super powers found
# 	./whirlwind.rb:39: A new array - should have super powers
# 	./whirlwind.rb:38
# 	./whirlwind.rb:3

$ bacon -k whirlwind.rb | kn-sum
6 tests, 1 failed (83.3333% succeeded)

(knock is available from github.com/chneukirchen/knock/)

Implemented assertions¶ ↑

should.<predicate> and should.be.<predicate>
should.equal
should.match
should.be.identical_to / should.be.same_as
should.raise(*exceptions) { }
should.change { }
should.throw(symbol) { }
should.satisfy { |object| }

Added core predicates¶ ↑

Object#true?
Object#false?
Proc#change?
Proc#raise?
Proc#throw?
Numeric#close?

before/after¶ ↑

before and after need to be defined before the first specification in a context and are run before and after each specification.

As of Bacon 1.1, before and after do nest in nested contexts.

Shared contexts¶ ↑

You can define shared contexts in Bacon like this:

shared "an empty container" do
  it "should have size zero" do
  end

  it "should be empty" do
  end
end

context "A new array" do
  behaves_like "an empty container"
end

These contexts are not executed on their own, but can be included with behaves_like in other contexts. You can use shared contexts to structure suites with many recurring specifications.

Matchers¶ ↑

Custom matchers are simply lambdas returning a boolean value, for example:

def shorter_than(max_size)
  lambda { |obj| obj.size < max_size }
end

[1,2,3].should.be shorter_than(5)

You can use modules and extend to group matchers for use in multiple contexts.

bacon standalone runner¶ ↑

-s, --specdox            do AgileDox-like output (default)
-q, --quiet              do Test::Unit-like non-verbose output
-p, --tap                do TAP (Test Anything Protocol) output
-k, --knock              do Knock output
-o, --output FORMAT      do FORMAT (SpecDox/TestUnit/Tap) output
-Q, --no-backtrace       don't print backtraces  
-a, --automatic          gather tests from ./test/, include ./lib/
-n, --name NAME          runs tests matching regexp NAME
-t, --testcase TESTCASE  runs tests in TestCases matching regexp TESTCASE

If you don’t want to use the standalone runner, run Bacon.summary_on_exit to install an exit handler showing the summary.

Object#should¶ ↑

You can use Object#should outside of contexts, where the result of assertion will be returned as a boolean. This is nice for demonstrations, quick checks and doctest tests.

>> require 'bacon'
>> (1 + 1).should.equal 2
=> true
>> (6*9).should.equal 42
=> false

Bacon with autotest¶ ↑

Since version 1.0, there is autotest support. You need to tag your test directories (test/ or spec/) by creating an .bacon file there. Autotest then will find it. bin/bacon needs to be in PATH or RUBYPATH.

Converting specs¶ ↑

spec-converter is a simple tool to convert test-unit or dust style tests to test/spec specs.

It can be found at opensource.thinkrelevance.com/wiki/spec_converter.

Thanks to¶ ↑

Michael Fellinger, for fixing Bacon for 1.9 and various improvements.
Gabriele Renzi, for implementing Context#should.
James Tucker, for the autotest support.
Yossef Mendelssohn, for nested contexts.
everyone contributing bug fixes.

History¶ ↑

January 7, 2008: First public release 0.9.
July 6th, 2008: Second public release 1.0.
- Add Context#should as a shortcut for Context#it(‘should ’ + _).
- describe now supports multiple arguments for better organization.
- Empty specifications are now erroneous.
- after-blocks run in the case of exceptions too.
- Autotest support.
- Bug fixes.
November 30th, 2008: Third public release 1.1.
- Nested before/after.
- Add -Q/–no-backtraces to not show details about failed specifications.
- Add Knock output.
- Bug fixes.
December 21th, 2012: Fourth public release 1.2.0.
- #satisfy will not pass arguments anymore to the block, use lexical scope.
- Fixed Context#change?.
- Add support for finding specs named like spec/*/_spec.rb.
- Contexts nest properly.
- Timer in TestUnitOutput.
- Nested output for SpecDoxOutput.
- Small cleanups and more tests.

Contact¶ ↑

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

Git repository (patches rebased on HEAD are most welcome): github.com/chneukirchen/bacon git://github.com/chneukirchen/bacon.git

Copying¶ ↑

Bacon is freely distributable under the terms of an MIT-style license. See COPYING or www.opensource.org/licenses/mit-license.php.

Links¶ ↑

Behavior-Driven Development: <behaviour-driven.org/>
RSpec: <rspec.rubyforge.org/>
test/spec: <test-spec.rubyforge.org/>
Christian Neukirchen: <chneukirchen.org/>

magiclin/bacon