riot 0.10.11 → 0.10.12.pre

data/Rakefile

@@ -1,47 +1,49 @@
 require 'rubygems'
 require 'rake'
 
-task :default => [:test]
+task :default => ["test:core", "test:assertion_macros"]
+task "test:all" => ["test:core", "test:assertion_macros", "test:extensions"]
 
 require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
+Rake::TestTask.new("test:core") do |test|
   test.libs    << 'test'
-  test.pattern =  'test/**/*_test.rb'
+  test.pattern =  'test/*_test.rb'
   test.warning =  true
   test.verbose =  false
 end
 
-desc "Run all of them fancy benchmarks, Howard!"
-task :benchmarks do
-  Dir["test/benchmark/*.rb"].each do |file|
-    puts ">> Running #{file}"
-    puts %x[ruby #{file}]
-  end
-end
-
-desc "Run Flog against library (except tests)"
-task :flog do
-  puts %x[find ./lib -name *.rb | xargs flog]
+Rake::TestTask.new("test:assertion_macros") do |test|
+  test.libs    << 'test'
+  test.pattern =  'test/assertion_macros/*_test.rb'
+  test.warning =  true
+  test.verbose =  false
 end
 
-desc "Run Flay against library (except tests)"
-task :flay do
-  puts %x[find ./lib -name *.rb | xargs flay]
+Rake::TestTask.new("test:extensions") do |test|
+  test.libs    << 'test'
+  test.pattern =  'test/extensions/*_test.rb'
+  test.warning =  true
+  test.verbose =  false
 end
 
-desc "Run Roodi against library (except tests)"
-task :roodi do
-  puts %x[find ./lib -name *.rb | xargs roodi]
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+  YARD::Rake::YardocTask.new do |t|
+    extra_files = %w(MIT-LICENSE)
+    t.files = ['lib/**/*.rb']
+    t.options = ["--files=#{extra_files.join(',')}"]
+  end
+rescue LoadError
+  # YARD isn't installed
 end
 
-desc "Stats on lines of code and test"
-task :stats do
-  loc = %x[find ./lib -name *.rb | xargs cat | wc -l].strip.to_i
-  lotc = %x[find ./test -name *.rb | xargs cat | wc -l].strip.to_i
-  total, ratio = (loc + lotc), (lotc / loc.to_f)
-
-  fmt = "  Code: %d\n  Test: %d\n       -----\n Total: %d  Ratio (test/code): %f"
-  puts fmt % [loc, lotc, loc + lotc, ratio]
+desc "Run all of them fancy benchmarks, Howard!"
+task :benchmarks do
+  Dir["test/benchmark/*.rb"].each do |file|
+    puts ">> Running #{file}"
+    puts %x[ruby #{file}]
+  end
 end
 
 #
@@ -56,6 +58,7 @@ begin
     gem.email = "gus@gusg.us"
     gem.homepage = "http://github.com/thumblemonks/riot"
     gem.authors = ["Justin 'Gus' Knowlden"]
+    gem.add_dependency 'rr'
     gem.add_dependency 'term-ansicolor'
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.10.11
+0.10.12.pre

data/lib/riot.rb

@@ -7,7 +7,7 @@ require 'riot/assertion_macro'
 
 module Riot
   def self.context(description, context_class = Context, &definition)
-    root_contexts << context_class.new(description, &definition)
+    (root_contexts << context_class.new(description, &definition)).last
   end
 
   def self.root_contexts; @root_contexts ||= []; end
@@ -20,6 +20,7 @@ module Riot
     the_reporter
   end
 
+  # This means you don't want to see any output from Riot. A "quiet riot" as Envy5 put it.
   def self.silently!; @silent = true; end
   def self.silently?; defined?(@silent) && @silent == true end
 

data/lib/riot/assertion.rb

@@ -1,7 +1,7 @@
 module Riot
   class Assertion < RunnableBlock
     class << self
-      def macros; @macros ||= {}; end
+      def macros; @@macros ||= {}; end
 
       def register_macro(name, assertion_macro, expect_exception=false)
         macros[name.to_s] = assertion_macro.new

data/lib/riot/assertion_macro.rb

@@ -1,15 +1,54 @@
+require 'riot/message'
+
 module Riot
+  # The base class for all assertion macros.
+  #
+  # == Using macros
+  #
+  # Macros are applied to the return value of assertions. For example, the
+  # `empty` macro asserts that the value is, well, empty, e.g.
+  #
+  #     asserts(:comments).empty?
+  #
+  # 
+  # == Writing your own macros
+  #
+  # Macros are added by subclassing {AssertionMacro}. For example, here's
+  # the implementation of `empty`:
+  #
+  #     class EmptyMacro < AssertionMacro
+  #       register :empty
+  #        
+  #       def evaluate(actual)
+  #         actual.length == 0 ? pass : fail(expected_message(actual).to_be_empty)
+  #       end
+  #     end
+  #
   class AssertionMacro
     class << self
+      # Whether the macro expects an exception to be thrown.
       attr_reader :expects_exception
 
-      def default; @default_macro ||= new; end
-      def expects_exception!; @expects_exception = true; end
-      def register(name); Assertion.register_macro name, self; end
+      # The default macro.
+      def default
+        @default_macro ||= new
+      end
+
+      # Specify that the macro expects an exception to be thrown by the assertion.
+      def expects_exception!
+        @expects_exception = true
+      end
+
+      # Register the macro under the given name.
+      #
+      # @param [Symbol] name the name of the macro
+      def register(name)
+        Assertion.register_macro name, self
+      end
     end
 
-    def pass(message=nil) [:pass, message]; end
-    def fail(message) [:fail, message]; end
+    def pass(message=nil) [:pass, message.to_s]; end
+    def fail(message) [:fail, message.to_s]; end
     def error(e) [:error, e]; end
 
     def expects_exception?; self.class.expects_exception; end
@@ -17,6 +56,12 @@ module Riot
     def evaluate(actual)
       actual ? pass : fail("Expected non-false but got #{actual.inspect} instead")
     end
+
+    # Messaging
+
+    def new_message(*phrases) Message.new(*phrases); end
+    def should_have_message(*phrases) new_message.should_have(*phrases); end
+    def expected_message(*phrases) new_message.expected(*phrases); end
   end
 end
 
@@ -24,6 +69,7 @@ require 'riot/assertion_macros/any'
 require 'riot/assertion_macros/assigns'
 require 'riot/assertion_macros/empty'
 require 'riot/assertion_macros/equals'
+require 'riot/assertion_macros/equivalent_to'
 require 'riot/assertion_macros/exists'
 require 'riot/assertion_macros/includes'
 require 'riot/assertion_macros/kind_of'

data/lib/riot/assertion_macros/any.rb

@@ -6,7 +6,7 @@ module Riot
     register :any
 
     def evaluate(actual)
-      actual.any? ? pass("is not empty") : fail("expected #{actual.inspect} to have items")
+      actual.any? ? pass("is not empty") : fail(expected_message(actual).to_have_items)
     end
   end
 end

data/lib/riot/assertion_macros/assigns.rb

@@ -16,9 +16,9 @@ module Riot
       variable_name = "@#{variable}"
       actual_value = actual.instance_variable_defined?(variable_name) ? actual.instance_variable_get(variable_name) : nil
       if actual_value.nil?
-        fail("expected @#{variable} to be assigned a value")
+        fail expected_message(variable).to_be_assigned_a_value
       elsif !expected_value.nil? && expected_value != actual_value
-        fail(%Q[expected @#{variable} to be equal to #{expected_value.inspect}, not #{actual_value.inspect}])
+        fail expected_message(variable).to_be_equal_to(expected_value).not(actual_value)
       else
         pass
       end

data/lib/riot/assertion_macros/empty.rb

@@ -7,7 +7,7 @@ module Riot
     register :empty
 
     def evaluate(actual)
-      actual.length == 0 ? pass : fail("expected #{actual.inspect} to be empty")
+      actual.length == 0 ? pass : fail(expected_message(actual).to_be_empty)
     end
   end
 end

data/lib/riot/assertion_macros/equals.rb

@@ -1,5 +1,5 @@
 module Riot
-  # Asserts that the result of the test equals the expected value. Using the +===+ operator to assert
+  # Asserts that the result of the test equals the expected value. Using the +==+ operator to assert
   # equality.
   #   asserts("test") { "foo" }.equals("foo")
   #   should("test") { "foo" }.equals("foo")
@@ -8,10 +8,10 @@ module Riot
     register :equals
 
     def evaluate(actual, expected)
-      if expected === actual
-        pass("is equal to #{expected.inspect}")
+      if expected == actual
+        pass new_message.is_equal_to(expected)
       else
-        fail("expected #{expected.inspect}, not #{actual.inspect}")
+        fail expected_message(expected).not(actual)
       end
     end
   end

data/lib/riot/assertion_macros/equivalent_to.rb

@@ -0,0 +1,22 @@
+module Riot
+  # Asserts that the result of the test is equivalent to the expected value. Using the +===+ operator.
+  #
+  #   asserts("test") { "foo" }.equivalent_to(String)
+  #   should("test") { "foo" }.equivalent_to("foo")
+  #   asserts("test") { "foo" }.equivalent_to { "foo" }
+  #
+  # Underneath the hood, this assertion macro says:
+  #
+  #   expected === actual
+  class EquivalentToMacro < AssertionMacro
+    register :equivalent_to
+
+    def evaluate(actual, expected)
+      if expected === actual
+        pass new_message.is_equivalent_to(expected)
+      else
+        fail expected_message(actual).to_be_equivalent_to(expected)
+      end
+    end
+  end
+end

data/lib/riot/assertion_macros/includes.rb

@@ -8,9 +8,9 @@ module Riot
 
     def evaluate(actual, expected)
       if actual.include?(expected)
-        pass("includes #{expected.inspect}")
+        pass new_message.includes(expected)
       else
-        fail("expected #{actual.inspect} to include #{expected.inspect}")
+        fail expected_message(actual).to_include(expected)
       end
     end
   end

data/lib/riot/assertion_macros/kind_of.rb

@@ -7,9 +7,9 @@ module Riot
 
     def evaluate(actual, expected)
       if actual.kind_of?(expected)
-        pass("is a kind of #{expected.inspect}")
+        pass new_message.is_a_kind_of(expected)
       else
-        fail("expected kind of #{expected}, not #{actual.class.inspect}")
+        fail expected_message.kind_of(expected).not(actual.class)
       end
     end
   end

data/lib/riot/assertion_macros/matches.rb

@@ -8,9 +8,9 @@ module Riot
     def evaluate(actual, expected)
       expected = %r[#{Regexp.escape(expected)}] if expected.kind_of?(String)
       if actual =~ expected
-        pass("matches #{expected.inspect}")
+        pass(new_message.matches(expected))
       else
-        fail("expected #{expected.inspect} to match #{actual.inspect}")
+        fail(expected_message(expected).to_match(actual))
       end
     end
   end

data/lib/riot/assertion_macros/nil.rb

@@ -6,7 +6,7 @@ module Riot
     register :nil
 
     def evaluate(actual)
-      actual.nil? ? pass("is nil") : fail("expected nil, not #{actual.inspect}")
+      actual.nil? ? pass("is nil") : fail(expected_message.nil.not(actual))
     end
   end
 end

data/lib/riot/assertion_macros/raises.rb

@@ -14,18 +14,15 @@ module Riot
     def evaluate(actual_exception, expected_class, expected_message=nil)
       actual_message = actual_exception && actual_exception.message
       if actual_exception.nil?
-        fail("should have raised #{expected_class}, but raised nothing")
+        fail should_have_message.raised(expected_class).but.raised_nothing
       elsif expected_class != actual_exception.class
-        fail("should have raised #{expected_class}, not #{actual_exception.class}")
+        fail should_have_message.raised(expected_class).not(actual_exception.class)
       elsif expected_message && !(actual_message.to_s =~ %r[#{expected_message}])
-        fail("expected #{expected_message.inspect} for message, not #{actual_message.inspect}")
+        fail expected_message(expected_message).for_message.not(actual_message)
       else
-        if expected_message
-          pass("raises #{expected_class.inspect} with message #{expected_message.inspect}")
-        else
-          pass("raises #{expected_class.inspect}")
-        end
+        message = new_message.raises(expected_class)
+        pass(expected_message ? message.with_message(expected_message) : message)
       end
-    end
-  end
+    end # evaluate
+  end # RaisesMacro
 end

data/lib/riot/assertion_macros/respond_to.rb

@@ -4,12 +4,13 @@ module Riot
   #   should("test") { "foo" }.respond_to(:to_s)
   class RespondToMacro < AssertionMacro
     register :respond_to
+    register :responds_to
 
     def evaluate(actual, expected)
       if actual.respond_to?(expected)
-        pass("responds to #{expected.inspect}")
+        pass(new_message.responds_to(expected))
       else
-        fail("expected method #{expected.inspect} is not defined")
+        fail(expected_message.method(expected).is_not_defined)
       end
     end
   end

data/lib/riot/assertion_macros/same_elements.rb

@@ -8,7 +8,7 @@ module Riot
     def evaluate(actual, expected)
       require 'set'
       same = (Set.new(expected) == Set.new(actual))
-      same ? pass : fail("expected elements #{expected.inspect} to match #{actual.inspect}")
+      same ? pass : fail(expected_message.elements(expected).to_match(actual))
     end
   end
 end

data/lib/riot/assertion_macros/size.rb

@@ -8,8 +8,8 @@ module Riot
     register :size
 
     def evaluate(actual, expected)
-      failure_message = "size of #{actual.inspect} expected to be #{expected} but is #{actual.size}"
-      expected === actual.size ? pass("is of size #{expected}") : fail(failure_message)
+      failure_message = expected_message.size_of(actual).to_be(expected).not(actual.size)
+      expected === actual.size ? pass(new_message.is_of_size(expected)) : fail(failure_message)
     end
   end
 end

data/lib/riot/context.rb

@@ -1,19 +1,68 @@
 module Riot
   RootContext = Struct.new(:setups, :teardowns)
 
+  module ContextHelpers
+    def assertion_class; Assertion; end
+    def situation_class; Situation; end
+  end
+
+  # You make your assertions within a Context. The context stores setup and
+  # teardown blocks, and allows for nesting and refactoring into helpers.
   class Context
+    include ContextHelpers
+    # The description of the context.
+    #
+    # @return [String]
     attr_reader :description
-    def initialize(description, parent=RootContext.new([],[]), &definition)
-      @parent = parent
+
+    # The parent context.
+    #
+    # @return [Riot::Context]
+    attr_reader :parent
+
+    def initialize(description, parent=nil, &definition)
+      @parent = parent || RootContext.new([],[])
       @description = description
-      @contexts, @setups, @assertions, @teardowns = [], [], [], []
+      @contexts, @helpers, @setups, @assertions, @teardowns = [], [], [], [], []
       self.instance_eval(&definition)
     end
 
-    def setups; @parent.setups + @setups; end
-    def teardowns; @parent.teardowns + @teardowns; end
+    # Create a new test context.
+    #
+    # @param [String] description
+    def context(description, &definition)
+      new_context(description, self.class, &definition)
+    end
+    
+    # Returns an ordered list of the setup blocks for the context.
+    #
+    # @return [Array[Riot::RunnableBlock]]
+    def setups
+      @parent.setups + @setups
+    end
+
+    # Returns an ordered list of the teardown blocks for the context.
+    #
+    # @return [Array[Riot::RunnableBlock]]
+    def teardowns
+      @parent.teardowns + @teardowns
+    end
     
-    def setup(&definition) (@setups << Setup.new(&definition)).last; end
+    # Add a setup block.
+    #
+    # A setup block defines the topic of the context. There can be multiple setup
+    # blocks; each can access the previous topic through the +topic+ attribute.
+    #
+    #   context "A string" do
+    #     setup { "foo" }
+    #     setup { topic * 2 }
+    #     asserts(:length).equals(6)
+    #   end
+    def setup(&definition)
+      (@setups << Setup.new(&definition)).last
+    end
+
+    def helper(name, &block); (@helpers << Helper.new(name, &block)).last; end
 
     # A setup shortcut that returns the original topic so you don't have to. Good for nested setups. Instead
     # of doing this in your context:
@@ -30,32 +79,68 @@ module Riot
       setup { self.instance_eval(&definition); topic }
     end
 
-    def teardown(&definition) (@teardowns << Setup.new(&definition)).last; end
+    # Add a teardown block.
+    def teardown(&definition)
+      (@teardowns << Setup.new(&definition)).last
+    end
 
-    def asserts(what, &definition) new_assertion("asserts", what, &definition); end
-    def should(what, &definition) new_assertion("should", what, &definition); end
-    def asserts_topic(what="topic"); asserts(what) { topic }; end
+    # Makes an assertion.
+    #
+    # In the most basic form, an assertion requires a descriptive name and a block.
+    #
+    #   asserts("#size is equals to 2") { topic.size == 2 }
+    #
+    # However, several shortcuts are available. Assertion macros can be added to the
+    # end, automating a number of common assertion patterns, e.g.
+    #
+    #   asserts("#size") { topic.size }.equals(2)
+    #
+    # Furthermore, the pattern of testing an attribute on the topic is codified as
+    #
+    #   asserts(:size).equals(2)
+    #
+    # Passing a Symbol to +asserts+ enables this behaviour. For more information on
+    # assertion macros, see {Riot::AssertionMacro}.
+    #
+    # @param [String, Symbol] what the property being tested
+    def asserts(what, &definition)
+      new_assertion("asserts", what, &definition)
+    end
 
-    def context(description, &definition)
-      @contexts << self.class.new("#{@description} #{description}", self, &definition)
+    def should(what, &definition)
+      new_assertion("should", what, &definition)
     end
-    
+
+    # Makes an assertion on the topic itself, e.g.
+    #
+    #   asserts_topic.matches(/^ab+/)
+    def asserts_topic(what="that it")
+      asserts(what) { topic }
+    end
+
     def run(reporter)
       reporter.describe_context(self) unless @assertions.empty?
-      local_run(reporter, Situation.new)
+      local_run(reporter, situation_class.new)
       run_sub_contexts(reporter)
       reporter
     end
-  private
 
     def local_run(reporter, situation)
-      (setups + @assertions + teardowns).each do |runnable|
-        reporter.report(runnable.to_s, runnable.run(situation))
-      end
+      runnables.each { |runnable| reporter.report(runnable.to_s, runnable.run(situation)) }
+    end
+
+  private
+
+    def runnables
+      setups + @helpers + @assertions + teardowns
     end
 
     def run_sub_contexts(reporter) @contexts.each { |ctx| ctx.run(reporter) }; end
 
+    def new_context(description, klass, &definition)
+      (@contexts << klass.new("#{@description} #{description}", self, &definition)).last
+    end
+
     def new_assertion(scope, what, &definition)
       if what.kind_of?(Symbol)
         definition ||= lambda { topic.send(what) }
@@ -64,7 +149,7 @@ module Riot
         description = "#{scope} #{what}"
       end
 
-      (@assertions << Assertion.new(description, &definition)).last
+      (@assertions << assertion_class.new(description, &definition)).last
     end
   end # Context
 end # Riot