← Back to branch summary

~ubuntu-branches/ubuntu/quantal/ruby1.9.1/quantal

« back to all changes in this revision

Viewing changes to lib/minitest/README.txt

  • Committer: Bazaar Package Importer
  • Author(s): Lucas Nussbaum
  • Date: 2011-09-24 19:16:17 UTC
  • mfrom: (1.1.8 upstream) (13.1.7 experimental)
  • Revision ID: james.westby@ubuntu.com-20110924191617-o1qz4rcmqjot8zuy
Tags: 1.9.3~rc1-1
http://bugs.debian.org/639959
* New upstream release: 1.9.3 RC1.
  + Includes load.c fixes. Closes: #639959.
* Upload to unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/minitest/README.txt
 
1
= minitest/*
 
2
 
 
3
* http://rubyforge.org/projects/bfts
 
4
 
 
5
== DESCRIPTION:
 
6
 
 
7
minitest provides a complete suite of testing facilities supporting
 
8
TDD, BDD, mocking, and benchmarking.
 
9
 
 
10
minitest/unit is a small and incredibly fast unit testing framework.
 
11
It provides a rich set of assertions to make your tests clean and
 
12
readable.
 
13
 
 
14
minitest/spec is a functionally complete spec engine. It hooks onto
 
15
minitest/unit and seamlessly bridges test assertions over to spec
 
16
expectations.
 
17
 
 
18
minitest/benchmark is an awesome way to assert the performance of your
 
19
algorithms in a repeatable manner. Now you can assert that your newb
 
20
co-worker doesn't replace your linear algorithm with an exponential
 
21
one!
 
22
 
 
23
minitest/mock by Steven Baker, is a beautifully tiny mock object
 
24
framework.
 
25
 
 
26
minitest/pride shows pride in testing and adds coloring to your test
 
27
output.
 
28
 
 
29
minitest/unit is meant to have a clean implementation for language
 
30
implementors that need a minimal set of methods to bootstrap a working
 
31
test suite. For example, there is no magic involved for test-case
 
32
discovery.
 
33
 
 
34
== FEATURES/PROBLEMS:
 
35
 
 
36
* minitest/autorun - the easy and explicit way to run all your tests.
 
37
* minitest/unit - a very fast, simple, and clean test system.
 
38
* minitest/spec - a very fast, simple, and clean spec system.
 
39
* minitest/mock - a simple and clean mock system.
 
40
* minitest/benchmark - an awesome way to assert your algorithm's performance.
 
41
* minitest/pride - show your pride in testing!
 
42
* Incredibly small and fast runner, but no bells and whistles.
 
43
 
 
44
== RATIONALE:
 
45
 
 
46
See design_rationale.rb to see how specs and tests work in minitest.
 
47
 
 
48
== SYNOPSIS:
 
49
 
 
50
Given that you'd like to test the following class:
 
51
 
 
52
  class Meme
 
53
    def i_can_has_cheezburger?
 
54
      "OHAI!"
 
55
    end
 
56
 
 
57
    def will_it_blend?
 
58
      "YES!"
 
59
    end
 
60
  end
 
61
 
 
62
=== Unit tests
 
63
 
 
64
  require 'minitest/autorun'
 
65
 
 
66
  class TestMeme < MiniTest::Unit::TestCase
 
67
    def setup
 
68
      @meme = Meme.new
 
69
    end
 
70
 
 
71
    def test_that_kitty_can_eat
 
72
      assert_equal "OHAI!", @meme.i_can_has_cheezburger?
 
73
    end
 
74
 
 
75
    def test_that_it_will_not_blend
 
76
      refute_match /^no/i, @meme.will_it_blend?
 
77
    end
 
78
  end
 
79
 
 
80
=== Specs
 
81
 
 
82
  require 'minitest/autorun'
 
83
 
 
84
  describe Meme do
 
85
    before do
 
86
      @meme = Meme.new
 
87
    end
 
88
 
 
89
    describe "when asked about cheeseburgers" do
 
90
      it "must respond positively" do
 
91
        @meme.i_can_has_cheezburger?.must_equal "OHAI!"
 
92
      end
 
93
    end
 
94
 
 
95
    describe "when asked about blending possibilities" do
 
96
      it "won't say no" do
 
97
        @meme.will_it_blend?.wont_match /^no/i
 
98
      end
 
99
    end
 
100
  end
 
101
 
 
102
=== Benchmarks
 
103
 
 
104
Add benchmarks to your regular unit tests. If the unit tests fail, the
 
105
benchmarks won't run.
 
106
 
 
107
  # optionally run benchmarks, good for CI-only work!
 
108
  require 'minitest/benchmark' if ENV["BENCH"]
 
109
 
 
110
  class TestMeme < MiniTest::Unit::TestCase
 
111
    # Override self.bench_range or default range is [1, 10, 100, 1_000, 10_000]
 
112
    def bench_my_algorithm
 
113
      assert_performance_linear 0.9999 do |n| # n is a range value
 
114
        n.times do
 
115
          @obj.my_algorithm
 
116
        end
 
117
      end
 
118
    end
 
119
  end
 
120
 
 
121
Or add them to your specs. If you make benchmarks optional, you'll
 
122
need to wrap your benchmarks in a conditional since the methods won't
 
123
be defined.
 
124
 
 
125
  describe Meme do
 
126
    if ENV["BENCH"] then
 
127
      bench_performance_linear "my_algorithm", 0.9999 do |n|
 
128
        100.times do
 
129
          @obj.my_algorithm(n)
 
130
        end
 
131
      end
 
132
    end
 
133
  end
 
134
 
 
135
outputs something like:
 
136
 
 
137
  # Running benchmarks:
 
138
 
 
139
  TestBlah      100     1000    10000
 
140
  bench_my_algorithm     0.006167        0.079279        0.786993
 
141
  bench_other_algorithm  0.061679        0.792797        7.869932
 
142
 
 
143
Output is tab-delimited to make it easy to paste into a spreadsheet.
 
144
 
 
145
=== Mocks
 
146
 
 
147
  class MemeAsker
 
148
    def initialize(meme)
 
149
      @meme = meme
 
150
    end
 
151
 
 
152
    def ask(question)
 
153
      method = question.tr(" ","_") + "?"
 
154
      @meme.send(method)
 
155
    end
 
156
  end
 
157
 
 
158
  require 'minitest/autorun'
 
159
 
 
160
  describe MemeAsker do
 
161
    before do
 
162
      @meme = MiniTest::Mock.new
 
163
      @meme_asker = MemeAsker.new @meme
 
164
    end
 
165
 
 
166
    describe "#ask" do
 
167
      describe "when passed an unpunctuated question" do
 
168
        it "should invoke the appropriate predicate method on the meme" do
 
169
          @meme.expect :will_it_blend?, :return_value
 
170
          @meme_asker.ask "will it blend"
 
171
          @meme.verify
 
172
        end
 
173
      end
 
174
    end
 
175
  end
 
176
 
 
177
=== Customizable Test Runner Types:
 
178
 
 
179
MiniTest::Unit.runner=(runner) provides an easy way of creating custom
 
180
test runners for specialized needs. Justin Weiss provides the
 
181
following real-world example to create an alternative to regular
 
182
fixture loading:
 
183
 
 
184
  class MiniTestWithHooks::Unit < MiniTest::Unit
 
185
    def before_suites
 
186
    end
 
187
 
 
188
    def after_suites
 
189
    end
 
190
 
 
191
    def _run_suites(suites, type)
 
192
      begin
 
193
        before_suites
 
194
        super(suites, type)
 
195
      ensure
 
196
        after_suites
 
197
      end
 
198
    end
 
199
 
 
200
    def _run_suite(suite, type)
 
201
      begin
 
202
        suite.before_suite
 
203
        super(suite, type)
 
204
      ensure
 
205
        suite.after_suite
 
206
      end
 
207
    end
 
208
  end
 
209
 
 
210
  module MiniTestWithTransactions
 
211
    class Unit < MiniTestWithHooks::Unit
 
212
      include TestSetupHelper
 
213
 
 
214
      def before_suites
 
215
        super
 
216
        setup_nested_transactions
 
217
        # load any data we want available for all tests
 
218
      end
 
219
 
 
220
      def after_suites
 
221
        teardown_nested_transactions
 
222
        super
 
223
      end
 
224
    end
 
225
  end
 
226
 
 
227
  MiniTest::Unit.runner = MiniTestWithTransactions::Unit.new
 
228
 
 
229
== REQUIREMENTS:
 
230
 
 
231
* Ruby 1.8, maybe even 1.6 or lower. No magic is involved.
 
232
 
 
233
== INSTALL:
 
234
 
 
235
  sudo gem install minitest
 
236
 
 
237
On 1.9, you already have it. To get newer candy you can still install
 
238
the gem, but you'll need to activate the gem explicitly to use it:
 
239
 
 
240
  require 'rubygems'
 
241
  gem 'minitest' # ensures you're using the gem, and not the built in MT
 
242
  require 'minitest/autorun'
 
243
  
 
244
  # ... usual testing stuffs ...
 
245
 
 
246
== LICENSE:
 
247
 
 
248
(The MIT License)
 
249
 
 
250
Copyright (c) Ryan Davis, Seattle.rb
 
251
 
 
252
Permission is hereby granted, free of charge, to any person obtaining
 
253
a copy of this software and associated documentation files (the
 
254
'Software'), to deal in the Software without restriction, including
 
255
without limitation the rights to use, copy, modify, merge, publish,
 
256
distribute, sublicense, and/or sell copies of the Software, and to
 
257
permit persons to whom the Software is furnished to do so, subject to
 
258
the following conditions:
 
259
 
 
260
The above copyright notice and this permission notice shall be
 
261
included in all copies or substantial portions of the Software.
 
262
 
 
263
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
 
264
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 
265
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 
266
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 
267
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 
268
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 
269
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.