mspec 1.3.1 → 1.4.0

data/README

@@ -91,6 +91,99 @@ All of these should be applied to a block created with `lambda` or `proc`:
   is associated with. The exception class can be given for finer-grained
   control (inheritance works normally so Exception would catch everything.)
 
+== Nested 'describe' blocks
+
+MSpec supports nesting one 'describe' block inside another. The examples in
+the nested block are evaluated with all the before/after blocks of all the
+containing 'describe' blocks. The following example illustrates this:
+
+describe "Some#method" do
+  before :each do
+    @obj = 1
+  end
+
+  describe "when passed String" do
+    before :each do
+      @meth = :to_s
+    end
+
+    it "returns false" do
+      # when this example is evaluated, @obj = 1 and @meth = :to_s
+    end
+  end
+end
+
+The output when using the SpecdocFormatter (selected with -fs to the runners)
+will be as follows:
+
+Some#method when passed String
+- returns false
+
+
+== Shared 'describe' blocks
+
+MSpec supports RSpec-style shared 'describe' blocks. MSpec also provides a
+convenience method to assist in writing specs for the numerous aliased methods
+that Ruby provides. The following example illustrates shared blocks:
+
+describe :someclass_some_method, :shared => true do
+  it "does something" do
+  end
+end
+
+describe "SomeClass#some_method" do
+  it_should_behave_like "someclass_some_method"
+end
+
+The first argument to 'describe' for a shared block is an object that
+duck-types as a String. The representation of the object must be unique. This
+example uses a symbol. This was the convention for the previous facility that
+MSpec provided for aliased method (#it_behaves_like). However, this convention
+is not set in stone (but the uniqueness requirement is). Note that the
+argument to the #it_should_behave_like is a String because at this time RSpec
+will not find the shared block by the symbol.
+
+MSpec continues to support the #it_behaves_like convenience method for
+specifying aliased methods. The syntax is as follows:
+
+it_behaves_like :symbol_matching_shared_describe, :method [, :object]
+
+describe :someclass_some_method, :shared => true do
+  it "returns true" do
+    obj.send(@method).should be_true
+  end
+
+  it "returns something else" do
+    @object.send(@method).should be_something_else
+  end
+end
+
+# example #1
+describe "SomeClass#some_method" do
+  it_behaves_like :someclass_some_method, :other_method
+end
+
+# example #2
+describe "SomeOtherClass#some_method" do
+  it_behaves_like :someclass_some_method, :some_method, OtherClass
+end
+
+The first form above (#1) is used for typical aliases. That is, methods with
+different names on the same class that behave identically. The
+#it_behaves_like helper creates a before(:all) block that sets @method to
+:other_method. The form of the first example block in the shared block
+illustrates the typical form of a spec for an aliased method.
+
+The second form above (#2) is used for methods on different classes that are
+essentially aliases, even though Ruby does not provide a syntax for specifying
+such methods as aliases. Examples are the methods on File, FileTest, and
+File::Stat. In this case, the #it_behaves_like helper sets both @method and
+@object in the before(:all) block (@method = :some_method, @object =
+OtherClass in this example).
+
+For shared specs that fall outside of either of these two narrow categories,
+use nested or shared 'describe' blocks as appropriate and use the
+#it_should_behave_like method directly.
 
 == Guards
 

data/lib/mspec/commands/mspec-ci.rb

@@ -61,8 +61,10 @@ class MSpecCI < MSpecScript
     MSpec.register_tags_patterns config[:tags_patterns]
     MSpec.register_files files
     TagFilter.new(:exclude, "fails").register
+    TagFilter.new(:exclude, "critical").register
     TagFilter.new(:exclude, "unstable").register
     TagFilter.new(:exclude, "incomplete").register
+    TagFilter.new(:exclude, "unsupported").register
 
     MSpec.process
     exit MSpec.exit_code

data/lib/mspec/matchers.rb

@@ -6,12 +6,13 @@ require 'mspec/matchers/be_false'
 require 'mspec/matchers/be_kind_of'
 require 'mspec/matchers/be_nil'
 require 'mspec/matchers/be_true'
-require 'mspec/matchers/equal'
+require 'mspec/matchers/complain'
 require 'mspec/matchers/eql'
+require 'mspec/matchers/equal'
+require 'mspec/matchers/equal_element'
+require 'mspec/matchers/equal_utf16'
 require 'mspec/matchers/include'
 require 'mspec/matchers/match_yaml'
 require 'mspec/matchers/raise_error'
 require 'mspec/matchers/output'
 require 'mspec/matchers/output_to_fd'
-require 'mspec/matchers/complain'
-require 'mspec/matchers/equal_utf16'

data/lib/mspec/matchers/equal_element.rb

@@ -0,0 +1,78 @@
+class EqualElementMatcher
+  def initialize(element, attributes = nil, content = nil, options = {})
+    @element = element
+    @attributes = attributes
+    @content = content
+    @options = options
+  end
+ 
+  def matches?(actual)
+    @actual = actual
+    
+    matched = true
+    
+    if @options[:not_closed]
+      matched &&= actual =~ /^#{Regexp.quote("<" + @element)}.*#{Regexp.quote(">" + (@content || ''))}$/
+    else
+      matched &&= actual =~ /^#{Regexp.quote("<" + @element)}/
+      matched &&= actual =~ /#{Regexp.quote("</" + @element + ">")}$/
+      matched &&= actual =~ /#{Regexp.quote(">" + @content + "</")}/ if @content      
+    end
+    
+    if @attributes
+      if @attributes.empty?
+        matched &&= actual.scan(/\w+\=\"(.*)\"/).size == 0
+      else
+        @attributes.each do |key, value|
+          if value == true
+            matched &&= (actual.scan(/#{Regexp.quote(key)}(\s|>)/).size == 1)
+          else
+            matched &&= (actual.scan(%Q{ #{key}="#{value}"}).size == 1)
+          end
+        end        
+      end
+    end
+    
+    !!matched
+  end
+ 
+  def failure_message
+    ["Expected #{@actual.pretty_inspect}",
+     "to be a '#{@element}' element with #{attributes_for_failure_message} and #{content_for_failure_message}"]
+  end
+ 
+  def negative_failure_message
+    ["Expected #{@actual.pretty_inspect}",
+      "not to be a '#{@element}' element with #{attributes_for_failure_message} and #{content_for_failure_message}"]
+  end
+
+  def attributes_for_failure_message
+    if @attributes
+      if @attributes.empty?
+        "no attributes"
+      else
+        @attributes.inject([]) { |memo, n| memo << %Q{#{n[0]}="#{n[1]}"} }.join(" ")
+      end
+    else
+      "any attributes"
+    end
+  end
+ 
+  def content_for_failure_message
+    if @content
+      if @content.empty?
+        "no content"
+      else  
+        "#{@content.inspect} as content"
+      end
+    else
+      "any content"
+    end
+  end
+end
+ 
+class Object
+  def equal_element(*args)
+    EqualElementMatcher.new(*args)
+  end
+end

data/lib/mspec/runner/context.rb

@@ -13,84 +13,170 @@ require 'mspec/runner/example'
 # is evaluated, just as +it+ refers to the example itself.
 #++
 class ContextState
-  attr_reader :state
-
-  def initialize
-    @start  = []
-    @before = []
-    @after  = []
-    @finish = []
-    @spec   = []
+  attr_reader :state, :parent, :parents, :children, :examples, :to_s
+
+  def initialize(mod, options=nil)
+    @to_s = mod.to_s
+    if options.is_a? Hash
+      @options = options
+    else
+      @to_s += "#{".:#".include?(options[0,1]) ? "" : " "}#{options}" if options
+      @options = { }
+    end
+    @options[:shared] ||= false
+
+    @parsed   = false
+    @before   = { :all => [], :each => [] }
+    @after    = { :all => [], :each => [] }
+    @pre      = {}
+    @post     = {}
+    @examples = []
+    @parent   = nil
+    @parents  = [self]
+    @children = []
+
     @mock_verify         = lambda { Mock.verify_count }
     @mock_cleanup        = lambda { Mock.cleanup }
     @expectation_missing = lambda { raise ExpectationNotFoundError }
   end
 
-  def before(at=:each, &block)
-    case at
-    when :each
-      @before << block
-    when :all
-      @start << block
-    end
+  # Returns true if this is a shared +ContextState+. Essentially, when
+  # created with: describe "Something", :shared => true { ... }
+  def shared?
+    return @options[:shared]
   end
 
-  def after(at=:each, &block)
-    case at
-    when :each
-      @after << block
-    when :all
-      @finish << block
+  # Set the parent (enclosing) +ContextState+ for this state. Creates
+  # the +parents+ list.
+  def parent=(parent)
+    @description = nil
+    @parent = parent
+    parent.child self if parent and not shared?
+
+    state = parent
+    while state
+      parents.unshift state
+      state = state.parent
     end
   end
 
+  # Add the ContextState instance +child+ to the list of nested
+  # describe blocks.
+  def child(child)
+    @children << child
+  end
+
+  # Returns a list of all before(+what+) blocks from self and any parents.
+  def pre(what)
+    @pre[what] ||= parents.inject([]) { |l, s| l.push(*s.before(what)) }
+  end
+
+  # Returns a list of all after(+what+) blocks from self and any parents.
+  # The list is in reverse order. In other words, the blocks defined in
+  # inner describes are in the list before those defined in outer describes,
+  # and in a particular describe block those defined later are in the list
+  # before those defined earlier.
+  def post(what)
+    @post[what] ||= parents.inject([]) { |l, s| l.unshift(*s.after(what)) }
+  end
+
+  # Records before(:each) and before(:all) blocks.
+  def before(what, &block)
+    block ? @before[what].push(block) : @before[what]
+  end
+
+  # Records after(:each) and after(:all) blocks.
+  def after(what, &block)
+    block ? @after[what].unshift(block) : @after[what]
+  end
+
+  # Creates an ExampleState instance for the block and stores it
+  # in a list of examples to evaluate unless the example is filtered.
   def it(desc, &block)
-    state = ExampleState.new @describe, desc
-    @spec << [desc, block, state] unless state.filtered?
+    @examples << ExampleState.new(self, desc, block)
+  end
+
+  # Evaluates the block and resets the toplevel +ContextState+ to #parent.
+  def describe(&block)
+    @parsed = protect @to_s, block, false
+    MSpec.register_current parent
+    MSpec.register_shared self if shared?
+  end
+
+  # Returns a description string generated from self and all parents
+  def description
+    @description ||= parents.inject([]) { |l,s| l << s.to_s }.join(" ")
   end
 
-  def describe(mod, desc=nil, &block)
-    @describe = desc ? "#{mod} #{desc}" : mod.to_s
-    @block = block
+  # Injects the before/after blocks and examples from the shared
+  # describe block into this +ContextState+ instance.
+  def it_should_behave_like(desc)
+    unless state = MSpec.retrieve_shared(desc)
+      raise Exception, "Unable to find shared 'describe' for #{desc}"
+    end
+
+    state.examples.each { |ex| ex.context = self; @examples << ex }
+    state.before(:all).each { |b| before :all, &b }
+    state.before(:each).each { |b| before :each, &b }
+    state.after(:each).each { |b| after :each, &b }
+    state.after(:all).each { |b| after :all, &b }
   end
 
+  # Evaluates each block in +blocks+ using the +MSpec.protect+ method
+  # so that exceptions are handled and tallied. Returns true and does
+  # NOT evaluate any blocks if +check+ is true and +MSpec.pretend_mode?+
+  # is true.
   def protect(what, blocks, check=true)
     return true if check and MSpec.pretend_mode?
     Array(blocks).all? { |block| MSpec.protect what, &block }
   end
 
+  # Removes filtered examples. Returns true if there are examples
+  # left to evaluate.
+  def filter_examples
+    @examples.reject! { |ex| ex.filtered? }
+    not @examples.empty?
+  end
+
+  # Evaluates the examples in a +ContextState+. Invokes the MSpec events
+  # for :enter, :before, :after, :leave.
   def process
-    protect @describe, @block, false
-    return unless @spec.any? { |desc, spec, state| state.unfiltered? }
-
-    MSpec.shuffle @spec if MSpec.randomize?
-    MSpec.actions :enter, @describe
-
-    if protect "before :all", @start
-      @spec.each do |desc, spec, state|
-        @state = state
-        MSpec.actions :before, state
-
-        if protect("before :each", @before)
-          MSpec.clear_expectations
-          passed = protect nil, spec
-          if spec
-            MSpec.actions :example, state, spec
-            protect nil, @expectation_missing unless MSpec.expectation? or not passed
+    MSpec.register_current self
+
+    if @parsed and filter_examples
+      MSpec.shuffle @examples if MSpec.randomize?
+      MSpec.actions :enter, description
+
+      if protect "before :all", pre(:all)
+        @examples.each do |state|
+          @state  = state
+          example = state.example
+          MSpec.actions :before, state
+
+          if protect "before :each", pre(:each)
+            MSpec.clear_expectations
+            if example
+              passed = protect nil, example
+              MSpec.actions :example, state, example
+              protect nil, @expectation_missing unless MSpec.expectation? or not passed
+            end
+            protect "after :each", post(:each)
+            protect "Mock.verify_count", @mock_verify
           end
-          protect "after :each", @after
-          protect "Mock.verify_count", @mock_verify
-        end
 
+          protect "Mock.cleanup", @mock_cleanup
+          MSpec.actions :after, state
+          @state = nil
+        end
+        protect "after :all", post(:all)
+      else
         protect "Mock.cleanup", @mock_cleanup
-        MSpec.actions :after, state
-        @state = nil
       end
-      protect "after :all", @finish
-    else
-      protect "Mock.cleanup", @mock_cleanup
+
+      MSpec.actions :leave
     end
 
-    MSpec.actions :leave
+    MSpec.register_current nil
+    children.each { |child| child.process }
   end
 end

data/lib/mspec/runner/example.rb

@@ -3,35 +3,32 @@ require 'mspec/runner/mspec'
 # Holds some of the state of the example (i.e. +it+ block) that is
 # being evaluated. See also +ContextState+.
 class ExampleState
-  def initialize(describe, it)
-    @describe = describe
-    @it = it
-    @unfiltered = nil
-  end
+  attr_reader   :context, :it, :example
 
-  def describe
-    @describe
+  def initialize(context, it, example=nil)
+    @context  = context
+    @it       = it
+    @example  = example
   end
 
-  def it
-    @it
+  def context=(context)
+    @description = nil
+    @context = context
   end
 
-  def description
-    @description ||= "#{@describe} #{@it}"
+  def describe
+    @context.description
   end
 
-  def unfiltered?
-    unless @unfiltered
-      incl = MSpec.retrieve(:include) || []
-      excl = MSpec.retrieve(:exclude) || []
-      @unfiltered   = incl.empty? || incl.any? { |f| f === description }
-      @unfiltered &&= excl.empty? || !excl.any? { |f| f === description }
-    end
-    @unfiltered
+  def description
+    @description ||= "#{describe} #{@it}"
   end
 
   def filtered?
-    not unfiltered?
+    incl = MSpec.retrieve(:include) || []
+    excl = MSpec.retrieve(:exclude) || []
+    included   = incl.empty? || incl.any? { |f| f === description }
+    included &&= excl.empty? || !excl.any? { |f| f === description }
+    not included
   end
 end