summary refs log tree commit diff
path: root/README
blob: 427f4940566d0ef89341904be84eda74ed57c4fb (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
= 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 300 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 http://chneukirchen.org/repos/taptap/)


== Implemented assertions

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


== Added core predicates

* Object#true?
* Object#false?
* 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.


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


== Contact

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

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


== Copying

Copyright (C) 2007 Christian Neukirchen <purl.org/net/chneukirchen>

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


== Links

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

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