riot 0.12.1 → 0.12.2

data/lib/riot/assertion_macros/exists.rb

@@ -16,12 +16,14 @@ module Riot
   class ExistsMacro < AssertionMacro
     register :exists
 
+    # (see Riot::AssertionMacro#evaluate)
     def evaluate(actual)
-      actual.nil? ? fail("expected a non-nil value") : pass("is not nil")
+      actual.nil? ? fail("expected a non-nil value") : pass("does exist")
     end
     
+    # (see Riot::AssertionMacro#devaluate)
     def devaluate(actual)
-      actual.nil? ? pass("is nil") : fail("expected a nil value")
+      actual.nil? ? pass("does exist") : fail("expected a nil value")
     end
   end
 end

data/lib/riot/assertion_macros/includes.rb

@@ -13,6 +13,8 @@ module Riot
   class IncludesMacro < AssertionMacro
     register :includes
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Object] expected the object that is expected to be included
     def evaluate(actual, expected)
       if actual.include?(expected)
         pass new_message.includes(expected)
@@ -21,11 +23,13 @@ module Riot
       end
     end
     
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Object] expected the object that is not expected to be included
     def devaluate(actual, expected)
       if actual.include?(expected)
         fail expected_message(actual).to_not_include(expected)
       else
-        pass new_message.does_not_include(expected)
+        pass new_message.includes(expected)
       end
     end
     

data/lib/riot/assertion_macros/kind_of.rb

@@ -10,6 +10,8 @@ module Riot
   class KindOfMacro < AssertionMacro
     register :kind_of
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Class] expected the expected class of actual
     def evaluate(actual, expected)
       if actual.kind_of?(expected)
         pass new_message.is_a_kind_of(expected)
@@ -18,11 +20,13 @@ module Riot
       end
     end
     
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Class] expected the unexpected class of actual
     def devaluate(actual, expected)
       if actual.kind_of?(expected)
         fail expected_message.not_kind_of(expected).not(actual.class)
       else
-        pass new_message.is_not_a_kind_of(expected)
+        pass new_message.is_a_kind_of(expected)
       end
     end
   end

data/lib/riot/assertion_macros/matches.rb

@@ -10,6 +10,8 @@ module Riot
   class MatchesMacro < AssertionMacro
     register :matches
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Regex, String] expected the string or regex to be used in comparison
     def evaluate(actual, expected)
       expected = %r[#{Regexp.escape(expected)}] if expected.kind_of?(String)
       if actual.to_s =~ expected
@@ -19,12 +21,14 @@ module Riot
       end
     end
     
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Regex, String] expected the string or regex to be used in comparison
     def devaluate(actual, expected)
       expected = %r[#{Regexp.escape(expected)}] if expected.kind_of?(String)
       if actual.to_s =~ expected
         fail(expected_message(expected).not_to_match(actual))
       else
-        pass(new_message.does_not_match(expected))
+        pass(new_message.matches(expected))
       end
     end
   end

data/lib/riot/assertion_macros/nil.rb

@@ -11,12 +11,14 @@ module Riot
   class NilMacro < AssertionMacro
     register :nil
 
+    # (see Riot::AssertionMacro#evaluate)
     def evaluate(actual)
       actual.nil? ? pass("is nil") : fail(expected_message.nil.not(actual))
     end
     
+    # (see Riot::AssertionMacro#devaluate)
     def devaluate(actual)
-      actual.nil? ? fail(expected_message.is_nil.not('non-nil')) : pass("is not nil")
+      actual.nil? ? fail(expected_message.is_nil.not('non-nil')) : pass("is nil")
     end
   end
 end

data/lib/riot/assertion_macros/not_borat.rb

@@ -12,14 +12,20 @@ module Riot
   # It would be kind of like a double negative:
   #
   #   denies("you are funny") { true }.not!
+  #
+  # @deprecated Please use the denies assertion instead
   class NotMacro < AssertionMacro
     register :not!
 
+    # (see Riot::AssertionMacro#evaluate)
     def evaluate(actual)
+      warn "not! is deprecated; please use the denies assertion instead"
       actual ? fail("expected to exist ... not!") : pass("does exist ... not!")
     end
     
+    # (see Riot::AssertionMacro#devaluate)
     def devaluate(actual)
+      warn "not! is deprecated; please use the denies assertion instead"
       actual ? pass("does not exist ... not!") : fail("expected to not exist ... not!")
     end
   end

data/lib/riot/assertion_macros/raises.rb

@@ -18,12 +18,15 @@ module Riot
     register :raises
     expects_exception!
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Class] expected_class the expected Exception class
+    # @param [String, nil] expected_message an optional exception message or message partial
     def evaluate(actual_exception, expected_class, expected_message=nil)
       actual_message = actual_exception && actual_exception.message
       if actual_exception.nil?
-        fail should_have_message.raised(expected_class).but.raised_nothing
+        fail new_message.expected_to_raise(expected_class).but.raised_nothing
       elsif expected_class != actual_exception.class
-        fail should_have_message.raised(expected_class).not(actual_exception.class)
+        fail new_message.expected_to_raise(expected_class).not(actual_exception.class)
       elsif expected_message && !(actual_message.to_s =~ %r[#{expected_message}])
         fail expected_message(expected_message).for_message.not(actual_message)
       else
@@ -32,23 +35,26 @@ module Riot
       end
     end # evaluate
 
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Class] expected_class the unexpected Exception class
+    # @param [String, nil] expected_message an optional exception message or message partial
     def devaluate(actual_exception, expected_class, expected_message=nil)
       actual_message = actual_exception && actual_exception.message
       if actual_exception.nil?
-        pass new_message.raised_nothing
+        pass new_message.raises(expected_class)
       elsif expected_class != actual_exception.class
         if expected_message && !(actual_message.to_s =~ %r[#{expected_message}])
-          pass new_message.not_raised(expected_class).with_message(expected_message)
+          pass new_message.raises(expected_class).with_message(expected_message)
         else
-          pass new_message.not_raised(expected_class)
+          pass new_message.raises(expected_class)
         end
       else
-        message = should_have_message.not_raised(expected_class)
+        message = new_message.expected_to_not_raise(expected_class)
         if expected_message
           fail message.with_message(expected_message).but.raised(actual_exception.class).
             with_message(actual_exception.message)
         else
-          fail message.but.raised(actual_exception.class)
+          fail message
         end
       end
     end # devaluate

data/lib/riot/assertion_macros/respond_to.rb

@@ -11,6 +11,8 @@ module Riot
     register :respond_to
     register :responds_to
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Symbol, String] expected the method name that actual should respond to
     def evaluate(actual, expected)
       if actual.respond_to?(expected)
         pass(new_message.responds_to(expected))
@@ -19,11 +21,13 @@ module Riot
       end
     end
     
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Symbol, String] expected the method name that actual should not respond to
     def devaluate(actual, expected)
       if actual.respond_to?(expected)
         fail(expected_message.method(expected).is_defined)
       else
-        pass new_message.does_not_respond_to(expected)
+        pass new_message.responds_to(expected)
       end
     end
     

data/lib/riot/assertion_macros/same_elements.rb

@@ -11,14 +11,18 @@ module Riot
     register :same_elements
     require 'set'
     
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Object] expected the collection of elements that actual should be equivalent to
     def evaluate(actual, expected)
       same = (Set.new(expected) == Set.new(actual))
-      same ? pass : fail(expected_message.elements(expected).to_match(actual))
+      same ? pass(new_message.has_same_elements_as(expected)) : fail(expected_message.elements(expected).to_match(actual))
     end
 
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Object] expected the collection of elements that actual should not be equivalent to
     def devaluate(actual, expected)
       same = (Set.new(expected) == Set.new(actual))
-      same ? fail(expected_message.elements(expected).not_to_match(actual)) : pass
+      same ? fail(expected_message.elements(expected).not_to_match(actual)) : pass(new_message.has_same_elements_as(expected))
     end
 
   end

data/lib/riot/assertion_macros/size.rb

@@ -14,14 +14,18 @@ module Riot
   class SizeMacro < AssertionMacro
     register :size
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Number] expected the expected size of actual
     def evaluate(actual, expected)
       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
 
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Number] expected the unexpected size of actual
     def devaluate(actual, expected)
       failure_message = expected_message.size_of(actual).to_not_be(expected).not(actual.size)
-      expected === actual.size ? fail(failure_message) : pass(new_message.is_not_size(expected))
+      expected === actual.size ? fail(failure_message) : pass(new_message.is_size(expected))
     end
   end
 end

data/lib/riot/context.rb

@@ -4,14 +4,24 @@ require 'riot/context_helpers'
 module Riot
   RootContext = Struct.new(:setups, :teardowns, :detailed_description, :options)
 
+  # Defines the classes {Riot::Context} will use when creating new assertions and situations.
   module ContextClassOverrides
+    # Returns the default class used for generating new {Riot::Assertion Assertion} instances. Defaults to
+    # {Riot::Assertion}.
+    #
+    # @return [Class]
     def assertion_class; Assertion; end
+
+    # Returns the default class used for generating new {Riot::Situation Situation} instances. Defaults to
+    # {Riot::Situation}.
+    #
+    # @return [Class]
     def situation_class; Situation; end
   end # ContextClassOverrides
 
-  # You make your assertions within a Context. The context stores setup and teardown blocks, and allows for
-  # nesting and refactoring into helpers. Extension developers may also configure ContextMiddleware objects
-  # in order to extend the functionality of a Context.
+  # An {Riot::Assertion} is declared within a Context. The context stores setup and teardown
+  # blocks, and allows for nesting and refactoring. Extension developers may also configure
+  # {Riot::ContextMiddleware Middleware} objects in order to extend the functionality of a Context.
   class Context
     include ContextClassOverrides
     include ContextOptions
@@ -19,19 +29,24 @@ module Riot
 
     # The set of middleware helpers configured for the current test space.
     #
-    # @return [Array]
+    # @return [Array<Riot::ContextMiddleware>]
     def self.middlewares; @middlewares ||= []; end
 
-    # The description of the context.
+    # The partial description of just this context.
     #
     # @return [String]
     attr_reader :description
 
     # The parent context.
     #
-    # @return [Riot::Context]
+    # @return [Riot::Context, nil] a context or nil
     attr_reader :parent
 
+    # Creates a new Context
+    #
+    # @param [String] description a partial description of this context
+    # @param [Riot::Context, nil] parent a parent context or nothing
+    # @param [lambda] definition the body of this context
     def initialize(description, parent=nil, &definition)
       @parent = parent || RootContext.new([],[], "", {})
       @description = description
@@ -43,25 +58,34 @@ module Riot
     # Create a new test context.
     #
     # @param [String] description
+    # @return [Riot::Context] the newly created context
     def context(description, &definition)
       new_context(description, self.class, &definition)
     end
     alias_method :describe, :context
 
+    # @private
     # Returns an ordered list of the setup blocks for the context.
     #
-    # @return [Array[Riot::RunnableBlock]]
+    # @return [Array<Riot::RunnableBlock>]
     def setups
       @parent.setups + @setups
     end
 
+    # @private
     # Returns an ordered list of the teardown blocks for the context.
     #
-    # @return [Array[Riot::RunnableBlock]]
+    # @return [Array<Riot::RunnableBlock>]
     def teardowns
       @parent.teardowns + @teardowns
     end
 
+    # Executes the setups, hookups, assertions, and teardowns and passes results on to a given
+    # {Riot::Reporter Reporter}. Sub-contexts will also be executed and provided the given reporter. A new
+    # {Riot::Situation Situation} will be created from the specified {#situation_class Situation class}.
+    #
+    # @param [Riot::Reporter] reporter the reporter to report results to
+    # @return [Riot::Reporter] the given reporter
     def run(reporter)
       reporter.describe_context(self) unless @assertions.empty?
       local_run(reporter, situation_class.new)
@@ -69,17 +93,26 @@ module Riot
       reporter
     end
 
+    # @private
+    # Used mostly for testing purposes; this method does the actual running of just this context.
+    # @param [Riot::Reporter] reporter the reporter to report results to
+    # @param [Riot::Situation] situation the situation to use for executing the context.
     def local_run(reporter, situation)
       runnables.each { |runnable| reporter.report(runnable.to_s, runnable.run(situation)) }
     end
 
-    # Prints the full description from the context tree
+    # Prints the full description from the context tree, grabbing the description from the parent and
+    # appending the description given to this context.
+    #
+    # @return [String] the full description for this context
     def detailed_description
       "#{parent.detailed_description} #{description}".strip
     end
 
   private
 
+    # Iterative over the registered middlewares and let them configure this context instance if they so
+    # choose. {Riot::AllImportantMiddleware} will always be the last in the chain.
     def prepare_middleware(&context_definition)
       last_middleware = AllImportantMiddleware.new(&context_definition)
       Context.middlewares.inject(last_middleware) do |last_middleware, middleware|
@@ -87,12 +120,27 @@ module Riot
       end.call(self)
     end
 
+    # The collection of things that are {Riot::RunnableBlock} instances in this context.
+    #
+    # @return [Array<Riot::RunnableBlock>]
     def runnables
       setups + @assertions + teardowns
     end
 
-    def run_sub_contexts(reporter) @contexts.each { |ctx| ctx.run(reporter) }; end
+    # Execute each sub context.
+    #
+    # @param [Riot::Reporter] reporter the reporter instance to use
+    # @return [nil]
+    def run_sub_contexts(reporter)
+      @contexts.each { |ctx| ctx.run(reporter) }
+    end
 
+    # Creates a new context instance and appends it to the set of immediate children sub-contexts.
+    #
+    # @param [String] description a partial description
+    # @param [Class] klass the context class that a sub-context will be generated from
+    # @param [lambda] definition the body of the sub-context
+    # @return [#run] something that hopefully responds to run and is context-like
     def new_context(description, klass, &definition)
       (@contexts << klass.new(description, self, &definition)).last
     end

data/lib/riot/context_helpers.rb

@@ -14,6 +14,9 @@ module Riot
     #
     # If you provide +true+ as the first argument, the setup will be unshifted onto the list of setups,
     # ensuring it will be run before any other setups. This is really only useful for context middlewares.
+    #
+    # @param [Boolean] premium indicates importance of the setup
+    # @return [Riot::Setup]
     def setup(premium=false, &definition)
       setup = Setup.new(&definition)
       premium ? @setups.unshift(setup) : @setups.push(setup)
@@ -29,6 +32,9 @@ module Riot
     #     helper(:foo) { "bar" }
     #     asserts("a foo") { foo }.equals("bar")
     #   end
+    #
+    # @param [String, Symbol] name the name of the helper
+    # @return [Riot::Helper]
     def helper(name, &block)
       (@setups << Helper.new(name, &block)).last
     end
@@ -44,6 +50,8 @@ module Riot
     # You would do this:
     #
     #   hookup { topic.do_something } # Yay!
+    #
+    # @return [Riot::Setup]
     def hookup(&definition)
       setup { self.instance_eval(&definition); topic }
     end
@@ -51,6 +59,8 @@ module Riot
     # Add a teardown block. You may define multiple of these as well.
     #
     #  teardown { Bombs.drop! }
+    #
+    # @return [Riot::Setup]
     def teardown(&definition)
       (@teardowns << Setup.new(&definition)).last
     end
@@ -73,7 +83,8 @@ module Riot
     # Passing a Symbol to +asserts+ enables this behaviour. For more information on
     # assertion macros, see {Riot::AssertionMacro}.
     #
-    # @param [String, Symbol] the property being tested
+    # @param [String, Symbol] what description of test or property to inspect on the topic
+    # @return [Riot::Assertion]
     def asserts(what, &definition)
       new_assertion("asserts", what, &definition)
     end
@@ -83,7 +94,8 @@ module Riot
     #
     #   should("ensure expected") { "bar" }.equals("bar")
     #
-    # @param [String, Symbol] the property being tested
+    # @param [String, Symbol] what description of test or property to inspect on the topic
+    # @return [Riot::Assertion]
     def should(what, &definition)
       new_assertion("should", what, &definition)
     end
@@ -106,7 +118,8 @@ module Riot
     # Passing a Symbol to +denies+ enables this behaviour. For more information on
     # assertion macros, see {Riot::AssertionMacro}.
     #
-    # @param [String, Symbol] the property being tested
+    # @param [String, Symbol] what description of test or property to inspect on the topic
+    # @return [Riot::Assertion]
     def denies(what, &definition)
       new_assertion("denies", what, true, &definition)
     end
@@ -114,6 +127,9 @@ module Riot
     # Makes an assertion on the topic itself, e.g.
     #
     #   asserts_topic.matches(/^ab+/)
+    #
+    # @param [String] what description of test
+    # @return [Riot::Assertion]
     def asserts_topic(what="that it")
       asserts(what) { topic }
     end
@@ -124,7 +140,7 @@ module Riot
         description = "#{scope} ##{what}"
       elsif what.kind_of?(Array)
         definition ||= proc { topic.send(*what) }
-        description = "#{scope} ##{what.shift} with argument(s): #{what}"
+        description = "#{scope} ##{what.first} with argument(s): #{what[1..-1]}"
       else
         description = "#{scope} #{what}"
       end