riot 0.12.1 → 0.12.2

data/Rakefile

@@ -1,7 +1,7 @@
-require 'rubygems'
-require 'rake'
+require 'bundler'
+Bundler::GemHelper.install_tasks
 
-task :default => ["test:all"]
+task :default   => ["test:all"]
 task "test:all" => ["test:core", "test:extensions"]
 
 require 'rake/testtask'
@@ -32,40 +32,5 @@ end
 desc "Run all of them fancy benchmarks, Howard!"
 task("test:benchmarks") { run_benchmarks("ruby") }
 
-desc "Run all of them fancy benchmarks in ruby-1.9, Steve!"
-task("test:benchmarks:1.9") { run_benchmarks("ruby1.9") }
-
-#
-# YARDie
-
-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
-
 #
 # Some monks like diamonds. I like gems.
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "riot"
-    gem.summary = "An extremely fast, expressive, and context-driven unit-testing framework. Protest the slow test."
-    gem.description = "An extremely fast, expressive, and context-driven unit-testing framework. A replacement for all other testing frameworks. Protest the slow test."
-    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
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end

data/lib/riot.rb

@@ -6,13 +6,33 @@ require 'riot/runnable'
 require 'riot/assertion'
 require 'riot/assertion_macro'
 
+# The namespace for all of Riot.
 module Riot
+  # A helper for creating/defining root context instances.
+  #
+  # @param [String] description the description of this context
+  # @param [Class] context_class the {Riot::Context} implementation to use
+  # @param [lambda] &definition the context definition
+  # @return [Context] the initialized {Riot::Context}
   def self.context(description, context_class = Context, &definition)
     (root_contexts << context_class.new(description, &definition)).last
   end
 
-  def self.root_contexts; @root_contexts ||= []; end
+  # The set of {Riot::Context} instances that have no parent.
+  #
+  # @return [Array] instances of {Riot::Context}
+  def self.root_contexts
+    @root_contexts ||= []
+  end
 
+  # How to run Riot itself. This should be called +at_exit+ unless you suggested - by calling {Riot.alone!}
+  # that you want to call this method yourself. If no {Riot.reporter} is set, the
+  # {Riot::StoryReporter default} will be used.
+  # 
+  # You can change reporters by setting the manually via {Riot.reporter=} or by using one of: {Riot.dots},
+  # {Riot.silently!}, or {Riot.verbose}.
+  #
+  # @return [Riot::Reporter] the reporter that was used
   def self.run
     the_reporter = reporter.new
     the_reporter.summarize do
@@ -21,16 +41,41 @@ 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
+  # This means you don't want to see any output from Riot. A "quiet riot".
+  def self.silently!
+    @silent = true
+  end
+
+  # Reponds to whether Riot is reporting silently.
+  #
+  # @return [Boolean]
+  def self.silently?
+    defined?(@silent) && @silent == true
+  end
 
   # This means you don't want Riot to run tests for you. You will execute Riot.run manually.
-  def self.alone!; @alone = true; end
-  def self.alone?; defined?(@alone) && @alone == true end
+  def self.alone!
+    @alone = true
+  end
 
-  def self.reporter=(reporter_class) @reporter_class = reporter_class; end
+  # Responds to whether Riot will run +at_exit+ (false) or manually (true).
+  #
+  # @return [Boolean]
+  def self.alone?
+    defined?(@alone) && @alone == true
+  end
 
+  # Allows the reporter class to be changed. Do this before tests are started.
+  #
+  # @param [Class] reporter_class the Class that represents a {Riot::Reporter}
+  def self.reporter=(reporter_class)
+    @reporter_class = reporter_class
+  end
+
+  # Returns the class for the reporter that is currently selected. If no reporter was explicitly selected,
+  # {Riot::StoryReporter} will be used.
+  #
+  # @return [Class] the Class that represents a {Riot::Reporter}
   def self.reporter
     if Riot.silently?
       Riot::SilentReporter
@@ -39,16 +84,34 @@ module Riot
     end
   end
 
-  # TODO: make this a flag that DotMatrix and Story respect and cause them to print errors/failures
-  def self.verbose; Riot.reporter = Riot::VerboseStoryReporter; end
-  def self.dots; Riot.reporter = Riot::DotMatrixReporter; end
+  # @todo make this a flag that DotMatrix and Story respect and cause them to print errors/failures
+  # Tells Riot to use {Riot::VerboseStoryReporter} for reporting
+  def self.verbose
+    Riot.reporter = Riot::VerboseStoryReporter
+  end
+
+  # Tells Riot to use {Riot::DotMatrixReporter} for reporting
+  def self.dots
+    Riot.reporter = Riot::DotMatrixReporter
+  end
+
+  # Tells Riot to use {Riot::PrettyDotMatrixReporter} for reporting
+  def self.pretty_dots
+    Riot.reporter = Riot::PrettyDotMatrixReporter
+  end
 
   at_exit { exit(run.success?) unless Riot.alone? }
 end # Riot
 
+# A little bit of monkey-patch so we can have +context+ available anywhere.
 class Object
+  # Defining +context+ in Object itself lets us define a root +context+ in any file. Any +context+ defined
+  # within a +context+ is already handled by {Riot::Context#context}.
+  #
+  # @param (see Riot.context)
+  # @return (see Riot.context)
   def context(description, context_class = Riot::Context, &definition)
     Riot.context(description, context_class, &definition)
   end
   alias_method :describe, :context
-end
+end # Object

data/lib/riot/assertion.rb

@@ -1,13 +1,36 @@
 module Riot
+  # An Assertion is the engine behind evaluating a single test that can be reported on. When +asserts+
+  # or +denies+ is used, the description and assertion block are used to generate a single Assertion
+  # instance. When running an Assertion, a [Riot::Situation] instance is required for data scoping. The
+  # result of calling run will be a status tuple that can be used for reporting.
+  #
+  # In general, you won't be spending much time in here.
   class Assertion < RunnableBlock
     class << self
+      # Returns the list of assertion macros that have been successfully registered
+      #
+      # @return [Hash<Riot::AssertionMacro>]
       def macros; @@macros ||= {}; end
 
-      def register_macro(name, assertion_macro, expect_exception=false)
+      # Registers a [Riot::AssertionMacro] class to a given +name+. Name is distinct, which means any future
+      # registrations for the same name will replace previous ones. +name+ will always be converted to a
+      # string first.
+      #
+      # @param [String, Symbol] name The handle the macro will be associated with
+      # @param [Class] assertion_macro A [Riot::AssertionMacro] class
+      def register_macro(name, assertion_macro)
         macros[name.to_s] = assertion_macro
       end
     end
 
+    # Setups a new Assertion. By default, the assertion will be a "positive" one, which means +evaluate+ will
+    # be call on the associated assertion macro. If +negative+ is true, +devaluate+ will be called instead.
+    # Not providing a definition block is just kind of silly since it's used to generate the +actual+ value
+    # for evaluation by a macro.
+    #
+    # @param [String] definition A small description of what this assertion is testing
+    # @param [Boolean] negative Determines whether this is a positive or negative assertion
+    # @param [lambda] definition The block that will return the +actual+ value when eval'ed
     def initialize(description, negative=false, &definition)
       super(description, &definition)
       @negative = negative
@@ -15,6 +38,14 @@ module Riot
       @macro = AssertionMacro.default
     end
 
+    # Given a {Riot::Situation}, execute the assertion definition provided to this Assertion, hand off to an
+    # assertion macro for evaluation, and then return a status tuple. If the macro to be used expects any
+    # exception, catch the exception and send to the macro; else just return it back.
+    #
+    # Currently supporting 3 evaluation states: :pass, :fail, and :error
+    # 
+    # @param [Riot::Situation] situation An instance of a {Riot::Situation}
+    # @return [Array<Symbol, String>] array containing evaluation state and a descriptive explanation
     def run(situation)
       @expectings << situation.evaluate(&@expectation_block) if @expectation_block
       actual = situation.evaluate(&definition)

data/lib/riot/assertion_macro.rb

@@ -6,15 +6,15 @@ module Riot
   # == 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.
+  # +empty+ macro asserts that the value is empty or denies that it is empty e.g.
   #
   #     asserts(:comments).empty?
-  #
+  #     denies(:comments).empty?
   # 
   # == Writing your own macros
   #
   # Macros are added by subclassing {AssertionMacro}. For example, here's
-  # the implementation of `empty`:
+  # the implementation of +empty+:
   #
   #     class EmptyMacro < AssertionMacro
   #       register :empty
@@ -31,9 +31,14 @@ module Riot
   class AssertionMacro
     class << self
       # Whether the macro expects an exception to be thrown.
+      #
+      # @return [Boolean]
       attr_reader :expects_exception
 
+      # @private
       # The default macro.
+      #
+      # @return [Riot::AssertionMacro]
       def default
         @default_macro ||= new
       end
@@ -45,34 +50,76 @@ module Riot
 
       # Register the macro under the given name.
       #
-      # @param [Symbol] name the name of the macro
+      # @param [String, Symbol] name the name of the macro
       def register(name)
         Assertion.register_macro name, self
       end
     end
 
-    attr_accessor :line, :file
+    # During failure reporting, what line number did the failure occur at
+    # @return [Number]
+    attr_accessor :line
 
+    # During failure reporting, what file did the failure occur in
+    # @return [String]
+    attr_accessor :file
+
+    # Returns a status tuple indicating the assertion passed.
+    #
+    # @param [String] message the message to report with
+    # @return [Array[Symbol, String]]
     def pass(message=nil) [:pass, message.to_s]; end
+
+    # Returns a status tuple indicating the assertion failed and where it failed it if that can be 
+    # determined.
+    #
+    # @param [String] message the message to report with
+    # @return [Array[Symbol, String, Number, String]]
     def fail(message) [:fail, message.to_s, line, file]; end
-    def error(e) [:error, e]; end
 
+    # Returns a status tuple indicating the assertion had an unexpected error.
+    #
+    # @param [Exception] ex the Exception that was captured
+    # @return [Array[Symbol, Exception]]
+    def error(ex) [:error, ex]; end
+
+    # Returns +true+ if this macro expects to handle Exceptions during evaluation.
+    #
+    # @return [boolean]
     def expects_exception?; self.class.expects_exception; end
 
-    # Supports positive assertion testing
+    # Supports positive assertion testing. This is where magic happens.
+    #
+    # @param [Object] actual the value returned from evaling the {Riot::Assertion Assertion} block
+    # @return [Array] response from either {#pass}, {#fail} or {#error}
     def evaluate(actual)
       actual ? pass : fail("Expected non-false but got #{actual.inspect} instead")
     end
 
-    # Supports negative/converse assertion testing
+    # Supports negative/converse assertion testing. This is also where magic happens.
+    #
+    # @param [Object] actual the value returned from evaling the {Riot::Assertion Assertion} block
+    # @return [Array] response from either {#pass}, {#fail} or {#error}
     def devaluate(actual)
       !actual ? pass : fail("Expected non-true but got #{actual.inspect} instead")
     end
 
-    # Messaging
-
+    # Creates a new message for use in any macro response that is initially empty.
+    #
+    # @param [Array<Object>] *phrases array of object whose values will be inspected and added to message
+    # @return [Riot::Message]
     def new_message(*phrases) Message.new(*phrases); end
+
+    # Creates a new message for use in any macro response that will start as "should have ".
+    #
+    # @param [Array<Object>] *phrases array of object whose values will be inspected and added to message
+    # @return [Riot::Message]
     def should_have_message(*phrases) new_message.should_have(*phrases); end
+
+    # Creates a new message for use in any macro response that will start as "expected ".
+    #
+    # @param [Array<Object>] *phrases array of object whose values will be inspected and added to message
+    # @return [Riot::Message]
     def expected_message(*phrases) new_message.expected(*phrases); end
   end
 end

data/lib/riot/assertion_macros/any.rb

@@ -11,12 +11,14 @@ module Riot
   class AnyMacro < AssertionMacro
     register :any
 
+    # (see Riot::AssertionMacro#evaluate)
     def evaluate(actual)
-      any?(actual) ? pass("is not empty") : fail(expected_message(actual).to_have_items)
+      any?(actual) ? pass("has items") : fail(expected_message(actual).to_have_items)
     end
 
+    # (see Riot::AssertionMacro#devaluate)
     def devaluate(actual)
-      any?(actual) ? fail(expected_message(actual).not_to_have_elements) : pass("has elements")
+      any?(actual) ? fail(expected_message(actual).not_to_have_items) : pass("has items")
     end
   private
     def any?(object)

data/lib/riot/assertion_macros/assigns.rb

@@ -20,25 +20,39 @@ module Riot
   class AssignsMacro < AssertionMacro
     register :assigns
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Symbol, String] variable name of instance variable to look for
+    # @param [Object, nil] expected_value an optional value to validate for the variable
     def evaluate(actual, *expectings)
       prepare(actual, *expectings) do |variable, expected_value, actual_value|
         if actual_value.nil?
           fail expected_message(variable).to_be_assigned_a_value
         elsif !expected_value.nil? && expected_value != actual_value
-          fail expected_message(variable).to_be_equal_to(expected_value).not(actual_value)
+          fail expected_message(variable).to_be_assigned_with(expected_value).not(actual_value)
         else
-          pass
+          if expected_value && actual_value
+            pass new_message.assigns(variable).with(expected_value)
+          else
+            pass new_message.assigns(variable)
+          end
         end
       end
     end
 
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Symbol, String] variable name of instance variable to look for
+    # @param [Object, nil] expected_value an optional value to validate for the variable
     def devaluate(actual, *expectings)
       prepare(actual, *expectings) do |variable, expected_value, actual_value|
         if actual_value.nil? || (expected_value && expected_value != actual_value)
-          pass
+          if expected_value && actual_value
+            pass new_message.assigns(variable).with(expected_value)
+          else
+            pass new_message.assigns(variable)
+          end
         else
           message = expected_message(variable).to_not_be
-          fail(expected_value.nil? ? message.assigned_a_value : message.equal_to(expected_value))
+          fail(expected_value.nil? ? message.assigned_a_value : message.assigned_with(expected_value))
         end
       end
     end

data/lib/riot/assertion_macros/empty.rb

@@ -13,10 +13,12 @@ module Riot
   class EmptyMacro < AssertionMacro
     register :empty
 
+    # (see Riot::AssertionMacro#evaluate)
     def evaluate(actual)
       actual.empty? ? pass(new_message.is_empty) : fail(expected_message(actual).to_be_empty)
     end
 
+    # (see Riot::AssertionMacro#devaluate)
     def devaluate(actual)
       actual.empty? ? fail(expected_message(actual).to_not_be_empty) : pass(new_message.is_empty)
     end

data/lib/riot/assertion_macros/equals.rb

@@ -14,6 +14,8 @@ module Riot
   class EqualsMacro < AssertionMacro
     register :equals
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Object] expected the object value to compare actual to
     def evaluate(actual, expected)
       if expected == actual
         pass new_message.is_equal_to(expected)
@@ -22,6 +24,8 @@ module Riot
       end
     end
 
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Object] expected the object value to compare actual to
     def devaluate(actual, expected)
       if expected != actual
         pass new_message.is_equal_to(expected).when_it_is(actual)

data/lib/riot/assertion_macros/equivalent_to.rb

@@ -16,6 +16,8 @@ module Riot
   class EquivalentToMacro < AssertionMacro
     register :equivalent_to
 
+    # (see Riot::AssertionMacro#evaluate)
+    # @param [Object] expected the object value to compare actual to
     def evaluate(actual, expected)
       if expected === actual
         pass new_message.is_equivalent_to(expected)
@@ -24,11 +26,13 @@ module Riot
       end
     end
     
+    # (see Riot::AssertionMacro#devaluate)
+    # @param [Object] expected the object value to compare actual to
     def devaluate(actual, expected)
       if expected === actual
         fail expected_message(actual).not_to_be_equivalent_to(expected)
       else
-        pass new_message.is_not_equivalent_to(expected)
+        pass new_message.is_equivalent_to(expected)
       end
     end