vendor/plugins/rspec/doc/src/documentation/test_unit.page

   1 ---
   2 title: Test::Unit Cheat Sheet
   3 ---
   4 h2. Coming from Test::Unit to RSpec
   5
   6 RSpec's expectation API is a superset of Test::Unit's assertion API. Use this table to
   7 find the RSpec equivalent of Test::Unit's asserts.
   8
   9 | Test::Unit                                           | RSpec                           | Comment                             |
  10 | assert(object)                                       | N/A                             | |
  11 | assert_block {...}                                   | lambda {...}.call.should be_true| |
  12 | assert_equal(expected, actual)                       | actual.should == expected       | Uses <code>==</code> |
  13 | ''                                                   | actual.should eql(expected)      | Uses <code>Object.eql?</code> |
  14 | assert_in_delta(expected_float, actual_float, delta) | actual_float.should be_close(expected_float, delta) | |
  15 | assert_instance_of(klass, object)                    | actual.should be_an_instance_of(klass) | |
  16 | assert_match(pattern, string)                        | string.should match(regexp)     | |
  17 | ''                                                   | string.should =~ regexp         | |
  18 | assert_nil(object)                                   | actual.should be_nil   | |
  19 | assert_no_match(regexp, string)                      | string.should_not match(regexp) | |
  20 | assert_not_equal(expected, actual)                   | actual.should_not eql(expected)       | Uses <code>!Object.eql?</code> |
  21 | assert_not_nil(object)                               | actual.should_not be_nil       | |
  22 | assert_not_same(expected, actual)                    | actual.should_not equal(nil)    | Uses <code>Object.equal?</code> |
  23 | assert_nothing_raised(*args) {...}                   | lambda {...}.should_not raise_error(Exception=nil, message=nil) |
  24 | assert_nothing_thrown {...}                          | lambda {...}.should_not throw_symbol(symbol=nil) |
  25 | assert_operator(object1, operator, object2)          | N/A | |
  26 | assert_raise(*args) {...}                            | lambda {...}.should raise_error(Exception=nil, message=nil) |
  27 | assert_raises(*args) {...}                           | lambda {...}.should raise_error(Exception=nil, message=nil) |
  28 | assert_respond_to(object, method)                    | actual.should respond_to(method) | |
  29 | assert_same(expected, actual)                        | actual.should equal(expected)         | Uses <code>!Object.equal?</code> |
  30 | assert_send(send_array)                              | N/A | |
  31 | assert_throws(expected_symbol, &proc)                | lambda {...}.should throw_symbol(symbol=nil) | |
  32 | flunk(message="Flunked")                             | violated(message=nil) | |
  33 | N/A                                                  | actual.should_be_something | Passes if object.something? is true |
  34
  35 h2. Regarding Equality
  36
  37 RSpec lets you express equality the same way Ruby does. This is different from
  38 Test::Unit and other xUnit frameworks, and this may cause some confusion for those
  39 of you who are making a switch.
  40
  41 Consider this example:
  42
  43 <ruby>words = "the words"
  44 assert_equals("the words", words) #passes
  45 assert_same("the words", words) #fails
  46 </ruby>
  47
  48 xUnit frameworks traditionally use method names like <code>#assert_equals</code> to
  49 imply object equivalence (objects with the same values) and method names like <code>#assert_same</code> to
  50 imply object identity (actually the same object). For programmers who are used to this syntax,
  51 it makes perfect sense to see this in a unit testing framework for Ruby.
  52
  53 The problem that we found is that Ruby handles equality differently from other languages. In
  54 java, for example, we override <code>Object#equals(other)</code> to describe object equivalence,
  55 whereas we use <code>==</code> to describe object identity. In Ruby, we do just the opposite.
  56 In fact, Ruby provides us with four ways to express equality:
  57
  58 <ruby>a == b
  59 a === b
  60 a.equal?(b)
  61 a.eql?(b)
  62 </ruby>
  63
  64 Each of these has its own semantics, which can (and often do) vary from class to class. In
  65 order to minimize the translation required to understand what an example might be expressing,
  66 we chose to express these directly in RSpec. If you understand Ruby equality, then you
  67 can understand what RSpec examples are describing:
  68
  69 <ruby>a.should == b      #passes if a == b
  70 a.should === b     #passes if a === b
  71 a.should equal(b)  #passes if a.equal?(b)
  72 a.should eql(b)    #passes if a.eql?(b)
  73 </ruby>
  74
  75 See "http://www.ruby-doc.org/core/classes/Object.html#M001057":http://www.ruby-doc.org/core/classes/Object.html#M001057 for
  76 more information about equality in Ruby.