mspec/README

   1  mSpec and mMock
   2 =================
   3
   4 mSpec and mMock are simplistic apes of RSpec.
   5
   6 The primary design rationale for mSpec is simplicity to allow nascent Ruby
   7 implementations to run the Ruby specs. So, for example, there is not great
   8 concern given to constant clashes. Namespacing (or module scoping) is not used
   9 because implementing this correctly took a significant amount of work in
  10 Rubinius and it is likely that other implementations would also face
  11 difficulties.
  12
  13 mSpec is not intended as a replacement for RSpec. mSpec attempts to provide a
  14 subset of RSpec syntax. It does not provide all the matchers, for instance.
  15
  16 mSpec also provides several extensions to facilitate writing the Ruby specs in
  17 a manner compatible with multiple Ruby implementations. First, mSpec offers a
  18 set of guards to control execution of the specs. These guards not only enable
  19 or disable execution but also annotate the specs with additional information
  20 about why they are run or not run. Second, mSpec provides a different shared
  21 spec implementation specifically designed to ease writing specs for the
  22 numerous aliased methods in Ruby. The mSpec shared spec implementation should
  23 not conflict with RSpec's own shared behavior facility.
  24
  25 Caveats:
  26 * Use RSpec to run the mSpec specs. There are no plans currently to make
  27   the mSpec specs runnable by mSpec.
  28 * Don't mock the #hash method as mMock uses Hash internally. This can be
  29   replaced if necessary, but at this point it's not worth it.
  30
  31
  32  Overview of Features
  33 ======================
  34
  35
  36  Matchers
  37 ----------
  38
  39 Matchers are additional aids for the verification process. The default
  40 is of course to #should or #should_not using the #== operator and its
  41 friends but the matchers add a new set of 'operators' to help in the
  42 task. They reside in `mspec/matchers/`. There are two broad categories,
  43 those that apply to an individual object and those that apply to a
  44 block:
  45
  46   Object
  47  --------
  48
  49 - `base` implements the standard #==, #< #<= #>= #> and #=~ with their
  50   normal semantics for the objects that you invoke them on.
  51
  52 - `be_ancestor_of` is equivalent to checking `obj.ancestors.include?`.
  53
  54 - `be_close` is a "delta" for floating-point math. Due to the very
  55   nature of it, floating-point comparisons should never be treated as
  56   exact. By default the tolerance is 0.00003 but it can be altered if
  57   so desired. So `0.23154.should be_close(0.23157)` would succeed
  58   (which is usually close enough for floating point unless you are
  59   doing some scientific computing.)
  60
  61 - `be_empty` checks `obj.empty?`
  62
  63 - `be_kind_of` is equivalent to `obj.kind_of?`
  64
  65 - `include` is `obj.include?`
  66
  67
  68   Block
  69  -------
  70
  71 All of these should be applied to a block created with `lambda` or `proc`:
  72
  73 - `complain` is probably clearer stated as `lambda {...}.should complain`;
  74   it checks that the block issues a warning. The message can be checked
  75   against either a String or a Regexp.
  76
  77 - `output` checks that the block produces the given output (stdout as well
  78   as stderr, in that order) matched either to a String or a Regexp. This one
  79   uses overrides so if that is a problem (for e.g. speccing Readline or
  80   something) see below.
  81
  82 - `output_to_fd` is a lower-level version and actually verifies that output
  83   to a certain file descriptor is correct whether from an in-/output stream
  84   or an actual file. Also can check with either a String or a Regexp.
  85
  86 - `raise_error` verifies the exception type (if any) raised by the block it
  87   is associated with. The exception class can be given for finer-grained
  88   control (inheritance works normally so Exception would catch everything.)
  89