1= minitest/{unit,spec,mock,benchmark}
2
3home :: https://github.com/seattlerb/minitest
4rdoc :: http://docs.seattlerb.org/minitest
5vim :: https://github.com/sunaku/vim-ruby-minitest
6
7== DESCRIPTION:
8
9minitest provides a complete suite of testing facilities supporting
10TDD, BDD, mocking, and benchmarking.
11
12 "I had a class with Jim Weirich on testing last week and we were
13 allowed to choose our testing frameworks. Kirk Haines and I were
14 paired up and we cracked open the code for a few test
15 frameworks...
16
17 I MUST say that minitest is *very* readable / understandable
18 compared to the 'other two' options we looked at. Nicely done and
19 thank you for helping us keep our mental sanity."
20
21 -- Wayne E. Seguin
22
23minitest/unit is a small and incredibly fast unit testing framework.
24It provides a rich set of assertions to make your tests clean and
25readable.
26
27minitest/spec is a functionally complete spec engine. It hooks onto
28minitest/unit and seamlessly bridges test assertions over to spec
29expectations.
30
31minitest/benchmark is an awesome way to assert the performance of your
32algorithms in a repeatable manner. Now you can assert that your newb
33co-worker doesn't replace your linear algorithm with an exponential
34one!
35
36minitest/mock by Steven Baker, is a beautifully tiny mock (and stub)
37object framework.
38
39minitest/pride shows pride in testing and adds coloring to your test
40output. I guess it is an example of how to write IO pipes too. :P
41
42minitest/unit is meant to have a clean implementation for language
43implementors that need a minimal set of methods to bootstrap a working
44test suite. For example, there is no magic involved for test-case
45discovery.
46
47 "Again, I can't praise enough the idea of a testing/specing
48 framework that I can actually read in full in one sitting!"
49
50 -- Piotr Szotkowski
51
52Comparing to rspec:
53
54 rspec is a testing DSL. minitest is ruby.
55
56 -- Adam Hawkins, "Bow Before MiniTest"
57
58minitest doesn't reinvent anything that ruby already provides, like:
59classes, modules, inheritance, methods. This means you only have to
60learn ruby to use minitest and all of your regular OO practices like
61extract-method refactorings still apply.
62
63== FEATURES/PROBLEMS:
64
65* minitest/autorun - the easy and explicit way to run all your tests.
66* minitest/unit - a very fast, simple, and clean test system.
67* minitest/spec - a very fast, simple, and clean spec system.
68* minitest/mock - a simple and clean mock/stub system.
69* minitest/benchmark - an awesome way to assert your algorithm's performance.
70* minitest/pride - show your pride in testing!
71* Incredibly small and fast runner, but no bells and whistles.
72
73== RATIONALE:
74
75See design_rationale.rb to see how specs and tests work in minitest.
76
77== SYNOPSIS:
78
79Given that you'd like to test the following class:
80
81 class Meme
82 def i_can_has_cheezburger?
83 "OHAI!"
84 end
85
86 def will_it_blend?
87 "YES!"
88 end
89 end
90
91=== Unit tests
92
93 require 'minitest/autorun'
94
95 class TestMeme < MiniTest::Unit::TestCase
96 def setup
97 @meme = Meme.new
98 end
99
100 def test_that_kitty_can_eat
101 assert_equal "OHAI!", @meme.i_can_has_cheezburger?
102 end
103
104 def test_that_it_will_not_blend
105 refute_match /^no/i, @meme.will_it_blend?
106 end
107
108 def test_that_will_be_skipped
109 skip "test this later"
110 end
111 end
112
113=== Specs
114
115 require 'minitest/autorun'
116
117 describe Meme do
118 before do
119 @meme = Meme.new
120 end
121
122 describe "when asked about cheeseburgers" do
123 it "must respond positively" do
124 @meme.i_can_has_cheezburger?.must_equal "OHAI!"
125 end
126 end
127
128 describe "when asked about blending possibilities" do
129 it "won't say no" do
130 @meme.will_it_blend?.wont_match /^no/i
131 end
132 end
133 end
134
135For matchers support check out:
136
137https://github.com/zenspider/minitest-matchers
138
139=== Benchmarks
140
141Add benchmarks to your regular unit tests. If the unit tests fail, the
142benchmarks won't run.
143
144 # optionally run benchmarks, good for CI-only work!
145 require 'minitest/benchmark' if ENV["BENCH"]
146
147 class TestMeme < MiniTest::Unit::TestCase
148 # Override self.bench_range or default range is [1, 10, 100, 1_000, 10_000]
149 def bench_my_algorithm
150 assert_performance_linear 0.9999 do |n| # n is a range value
151 @obj.my_algorithm(n)
152 end
153 end
154 end
155
156Or add them to your specs. If you make benchmarks optional, you'll
157need to wrap your benchmarks in a conditional since the methods won't
158be defined.
159
160 describe Meme do
161 if ENV["BENCH"] then
162 bench_performance_linear "my_algorithm", 0.9999 do |n|
163 100.times do
164 @obj.my_algorithm(n)
165 end
166 end
167 end
168 end
169
170outputs something like:
171
172 # Running benchmarks:
173
174 TestBlah 100 1000 10000
175 bench_my_algorithm 0.006167 0.079279 0.786993
176 bench_other_algorithm 0.061679 0.792797 7.869932
177
178Output is tab-delimited to make it easy to paste into a spreadsheet.
179
180=== Mocks
181
182 class MemeAsker
183 def initialize(meme)
184 @meme = meme
185 end
186
187 def ask(question)
188 method = question.tr(" ","_") + "?"
189 @meme.__send__(method)
190 end
191 end
192
193 require 'minitest/autorun'
194
195 describe MemeAsker do
196 before do
197 @meme = MiniTest::Mock.new
198 @meme_asker = MemeAsker.new @meme
199 end
200
201 describe "#ask" do
202 describe "when passed an unpunctuated question" do
203 it "should invoke the appropriate predicate method on the meme" do
204 @meme.expect :will_it_blend?, :return_value
205 @meme_asker.ask "will it blend"
206 @meme.verify
207 end
208 end
209 end
210 end
211
212=== Stubs
213
214 def test_stale_eh
215 obj_under_test = Something.new
216
217 refute obj_under_test.stale?
218
219 Time.stub :now, Time.at(0) do # stub goes away once the block is done
220 assert obj_under_test.stale?
221 end
222 end
223
224=== Customizable Test Runner Types:
225
226MiniTest::Unit.runner=(runner) provides an easy way of creating custom
227test runners for specialized needs. Justin Weiss provides the
228following real-world example to create an alternative to regular
229fixture loading:
230
231 class MiniTestWithHooks::Unit < MiniTest::Unit
232 def before_suites
233 end
234
235 def after_suites
236 end
237
238 def _run_suites(suites, type)
239 begin
240 before_suites
241 super(suites, type)
242 ensure
243 after_suites
244 end
245 end
246
247 def _run_suite(suite, type)
248 begin
249 suite.before_suite
250 super(suite, type)
251 ensure
252 suite.after_suite
253 end
254 end
255 end
256
257 module MiniTestWithTransactions
258 class Unit < MiniTestWithHooks::Unit
259 include TestSetupHelper
260
261 def before_suites
262 super
263 setup_nested_transactions
264 # load any data we want available for all tests
265 end
266
267 def after_suites
268 teardown_nested_transactions
269 super
270 end
271 end
272 end
273
274 MiniTest::Unit.runner = MiniTestWithTransactions::Unit.new
275
276== Known Extensions:
277
278minitest-capistrano :: Assertions and expectations for testing Capistrano recipes
279minitest-capybara :: Capybara matchers support for minitest unit and spec
280minitest-chef-handler :: Run Minitest suites as Chef report handlers
281minitest-ci :: CI reporter plugin for MiniTest.
282minitest-colorize :: Colorize MiniTest output and show failing tests instantly.
283minitest-context :: Defines contexts for code reuse in MiniTest
284 specs that share common expectations.
285minitest-debugger :: Wraps assert so failed assertions drop into
286 the ruby debugger.
287minitest-display :: Patches MiniTest to allow for an easily configurable output.
288minitest-emoji :: Print out emoji for your test passes, fails, and skips.
289minitest-excludes :: Clean API for excluding certain tests you
290 don't want to run under certain conditions.
291minitest-firemock :: Makes your MiniTest mocks more resilient.
292minitest-growl :: Test notifier for minitest via growl.
293minitest-instrument :: Instrument ActiveSupport::Notifications when
294 test method is executed
295minitest-instrument-db :: Store information about speed of test
296 execution provided by minitest-instrument in database
297minitest-libnotify :: Test notifier for minitest via libnotify.
298minitest-macruby :: Provides extensions to minitest for macruby UI testing.
299minitest-matchers :: Adds support for RSpec-style matchers to minitest.
300minitest-metadata :: Annotate tests with metadata (key-value).
301minitest-mongoid :: Mongoid assertion matchers for MiniTest
302minitest-must_not :: Provides must_not as an alias for wont in MiniTest
303minitest-predicates :: Adds support for .predicate? methods
304minitest-rails :: MiniTest integration for Rails 3.x
305minitest-rails-capybara :: Capybara integration for MiniTest::Rails
306minitest-reporters :: Create customizable MiniTest output formats
307minitest-rg :: redgreen minitest
308minitest-shouldify :: Adding all manner of shoulds to MiniTest (bad idea)
309minitest-spec-magic :: Minitest::Spec extensions for Rails and beyond
310minitest-tags :: add tags for minitest
311minitest-wscolor :: Yet another test colorizer.
312minitest_owrapper :: Get tests results as a TestResult object.
313minitest_should :: Shoulda style syntax for minitest test::unit.
314minitest_tu_shim :: minitest_tu_shim bridges between test/unit and minitest.
315mongoid-minitest :: MiniTest matchers for Mongoid.
316pry-rescue :: A pry plugin w/ minitest support. See pry-rescue/minitest.rb.
317
318== Unknown Extensions:
319
320Authors... Please send me a pull request with a description of your minitest extension.
321
322* assay-minitest
323* capybara_minitest_spec
324* detroit-minitest
325* em-minitest-spec
326* flexmock-minitest
327* guard-minitest
328* guard-minitest-decisiv
329* minitest-activemodel
330* minitest-ar-assertions
331* minitest-around
332* minitest-capybara-unit
333* minitest-colorer
334* minitest-deluxe
335* minitest-extra-assertions
336* minitest-nc
337* minitest-rails-shoulda
338* minitest-spec
339* minitest-spec-context
340* minitest-spec-rails
341* minitest-spec-should
342* minitest-sugar
343* minitest_should
344* mongoid-minitest
345* spork-minitest
346
347== REQUIREMENTS:
348
349* Ruby 1.8, maybe even 1.6 or lower. No magic is involved.
350
351== INSTALL:
352
353 sudo gem install minitest
354
355On 1.9, you already have it. To get newer candy you can still install
356the gem, but you'll need to activate the gem explicitly to use it:
357
358 require 'rubygems'
359 gem 'minitest' # ensures you're using the gem, and not the built in MT
360 require 'minitest/autorun'
361
362 # ... usual testing stuffs ...
363
364DO NOTE: There is a serious problem with the way that ruby 1.9/2.0
365packages their own gems. They install a gem specification file, but
366don't install the gem contents in the gem path. This messes up
367Gem.find_files and many other things (gem which, gem contents, etc).
368
369Just install minitest as a gem for real and you'll be happier.
370
371== LICENSE:
372
373(The MIT License)
374
375Copyright (c) Ryan Davis, seattle.rb
376
377Permission is hereby granted, free of charge, to any person obtaining
378a copy of this software and associated documentation files (the
379'Software'), to deal in the Software without restriction, including
380without limitation the rights to use, copy, modify, merge, publish,
381distribute, sublicense, and/or sell copies of the Software, and to
382permit persons to whom the Software is furnished to do so, subject to
383the following conditions:
384
385The above copyright notice and this permission notice shall be
386included in all copies or substantial portions of the Software.
387
388THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
389EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
390MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
391IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
392CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
393TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
394SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
395