riot 0.12.1 → 0.12.2

data/lib/riot/reporter/dot_matrix.rb

@@ -0,0 +1,49 @@
+module Riot
+
+  # Outputs in the dot-notion almost everyone should be familiar with, "." implies pass, "F" implues a
+  # failure, and "E" implies an error. If ansi-coloring is available, it is used. Error and failure messages
+  # are buffered for output until the end.
+  class DotMatrixReporter < IOReporter
+    # Creates a new DotMatrixReporter and initializes the failure/error details buffer.
+    # @param (see Riot::IOReporter#initialize)
+    def initialize(writer=STDOUT)
+      super
+      @details = []
+    end
+
+    # Prints a ".". Prints in green if possible.
+    #
+    # @param (see Riot::Reporter#pass)
+    def pass(description, message)
+      print green(".")
+    end
+
+    # Prints a "F" and saves the failure details (including line number and file) for the end.
+    # Prints in yellow if possible.
+    #
+    # @param (see Riot::Reporter#fail)
+    def fail(description, message, line, file)
+      print yellow("F")
+      @details << "FAILURE - #{test_detail(description, message)} #{line_info(line, file)}".strip
+    end
+
+    # Prints a "E" and saves the error details (including backtrace) for the end. Prints in red if possible.
+    #
+    # @param (see Riot::Reporter#error)
+    def error(description, e)
+      print red("E")
+      @details << "ERROR - #{test_detail(description, format_error(e))}"
+    end
+
+    # (see Riot::Reporter#results)
+    def results(time_taken)
+      puts "\n#{@details.join("\n\n")}" unless @details.empty?
+      super
+    end
+  private
+    def test_detail(description, message)
+      "#{current_context.detailed_description} #{description} => #{message}"
+    end
+  end # DotMatrixReporter
+
+end # Riot

data/lib/riot/reporter/io.rb

@@ -0,0 +1,85 @@
+module Riot
+
+  # An IOReporter is one that expects to use an IO object to output results to. Thus, whatever is available
+  # by an instance of an IO object should be available to whatever is given to this reporter to use.
+  #
+  # This is an abstract class. You should use some other or define your own sub-class that knows how to
+  # handle +pass+, +fail+, and +error+.
+  class IOReporter < Reporter
+    # Creates a new IOReporter. You can give it your own IO writer or it will default to +STDOUT+.
+    #
+    # @param [IO] writer the writer to use for results
+    def initialize(writer=STDOUT)
+      super()
+      @writer = writer
+    end
+
+    # (see Riot::Reporter#results)
+    def results(time_taken)
+      values = [passes, failures, errors, ("%0.6f" % time_taken)]
+      puts "\n%d passes, %d failures, %d errors in %s seconds" % values
+    end
+
+  protected
+    # Helper that knows how to write output to the writer with a newline.
+    #
+    # @param [String] message the message to be printed
+    def puts(message) @writer.puts(message); end
+
+    # Helper that knows how to write output to the writer without a newline.
+    #
+    # @param [String] message the message to be printed
+    def print(message) @writer.print(message); end
+
+    # Takes a line number, the file it corresponds to, and generates a formatted string for use in failure
+    # responses.
+    #
+    # @param [Number] line the line number of the failure
+    # @param [String] file the name of the file the failure was in
+    # @return [String] formatted failure line
+    def line_info(line, file)
+      line ? "(on line #{line} in #{file})" : ""
+    end
+
+    # Generates a message for assertions that error out. However, in the additional stacktrace, any mentions 
+    # of Riot and Rake framework methods calls are removed. Makes for a more readable error response.
+    #
+    # @param [Exception] e the exception to generate the backtrace from
+    # @return [String] the error response message
+    def format_error(e)
+      format = []
+      format << "    #{e.class.name} occurred"
+      format << "#{e.to_s}"
+      filter_backtrace(e.backtrace) { |line| format << "      at #{line}" }
+
+      format.join("\n")
+    end
+
+    # Filters Riot and Rake method calls from an exception backtrace.
+    #
+    # @param [Array] backtrace an exception's backtrace
+    # @param [lambda] &line_handler called each time a good line is found
+    def filter_backtrace(backtrace, &line_handler)
+      cleansed, bad = [], true
+
+      # goal is to filter all the riot stuff/rake before the first non riot thing
+      backtrace.reverse_each do |bt|
+        # make sure we are still in the bad part
+        bad = (bt =~ /\/lib\/riot/ || bt =~ /rake_test_loader/) if bad
+        yield bt unless bad
+      end
+    end
+
+    # Color output
+    def red(str);    with_color(31, str); end
+    def yellow(str); with_color(33, str); end
+    def green(str);  with_color(32, str); end
+    
+    # for color reference:
+    # http://www.pixelbeat.org/docs/terminal_colours/
+    def with_color(code,str)
+      "\e[#{code}m#{str}\e[0m"
+    end
+  end # IOReporter
+
+end # Riot

data/lib/riot/reporter/pretty_dot_matrix.rb

@@ -0,0 +1,38 @@
+module Riot
+
+  # This is essentially just DotMatrix with the legacy DotMatrix formatting, slightly better.
+  # Failure and Error outputs are color labeled and are formatted neatly and 
+  # concisely under each associated label.
+  # example:
+  # ........FE....
+  # FAILURE
+  #  A failure would have a message like this => expected 1, not 0
+  #  (on line 26 in test/core/blah.rb)
+  # ERROR
+  #  A reporter asserts this errors => Exception occured
+  #  at test/core/report_test.rb:24:in `block (2 levels) in <top (required)>'
+  #
+  class PrettyDotMatrixReporter < DotMatrixReporter
+
+    # Prints a yellow F and formats the Fail messages a bit better
+    # than the default DotMatrixReporter
+    def fail(description, message, line, file)
+      print yellow('F')
+      @details << "#{yellow("FAILURE")}\n #{test_detail(description, message)}\n #{line_info(line, file)}".strip
+    end
+
+    # Prints out an red E and formats the fail message better
+    def error(description, e)
+      print red('E')
+      @details << "#{red("ERROR")}\n #{test_detail(description,"#{e} occured")}\n #{simple_error(e)}"
+    end
+
+    def simple_error(e)
+      format = []
+      filter_backtrace(e.backtrace) { |line| format << "at #{line}" }
+
+      format.join("\n")
+    end
+  end
+end
+

data/lib/riot/reporter/silent.rb

@@ -0,0 +1,18 @@
+module Riot
+
+  # Basically, the Null Object pattern; nothing is output from this reporter.
+  class SilentReporter < Reporter
+    # (see Riot::Reporter#pass)
+    def pass(description, message); end
+
+    # (see Riot::Reporter#fail)
+    def fail(description, message, line, file); end
+
+    # (see Riot::Reporter#error)
+    def error(description, e); end
+
+    # (see Riot::Reporter#results)
+    def results(time_taken); end
+  end # SilentReporter
+
+end # Riot

data/lib/riot/reporter/story.rb

@@ -0,0 +1,52 @@
+module Riot
+
+  # For each context that is started and assertion that is run, its description is printed to the console
+  # on its own line. Regarding assertions, if ansi-colors are available then passing assertions are printed
+  # in green, failing in yellow, and errors in red. Note that backtraces are not reported for errors; see
+  # {Riot::VerboseStoryReporter}.
+  class StoryReporter < IOReporter
+    # Prints the descrition of the context on its own line
+    #
+    # @param (see Riot::Reporter#describe_context)
+    def describe_context(context)
+      super
+      puts context.detailed_description
+    end
+
+    # Prints the description of the assertion. Prints in green if possible.
+    #
+    # @param (see Riot::Reporter#pass)
+    def pass(description, message)
+      puts "  + " + green("#{description} #{message}".strip)
+    end
+
+    # Prints the description of the assertion and the line number of the failure. Prints in yellow if
+    # possible.
+    #
+    # @param (see Riot::Reporter#fail)
+    def fail(description, message, line, file)
+      puts "  - " + yellow("#{description}: #{message} #{line_info(line, file)}".strip)
+    end
+
+    # Prints the description of the assertion and the exception message. Prints in red if
+    # possible.
+    #
+    # @param (see Riot::Reporter#error)
+    def error(description, e)
+      puts "  ! " + red("#{description}: #{e.message}")
+    end
+  end # StoryReporter
+
+  # Same as {Riot::StoryReporter} except that backtraces are printed for assertions with errors
+  class VerboseStoryReporter < StoryReporter
+    # Prints the description of the assertion and the exception backtrace. Prints in red if
+    # possible.
+    #
+    # @param (see Riot::Reporter#error)
+    def error(description, e)
+      super
+      puts red(format_error(e))
+    end
+  end # VerboseStoryReporter
+
+end # Riot

data/lib/riot/rr.rb

@@ -1,13 +1,29 @@
 require 'rr'
 
 module Riot
+  # Enables inherent RR support in Riot. When required in, all contexts and assertions are adapted to have
+  # RR support.
   module RR
 
+    # Basically, provides a {Riot::Situation} that has been adapted to RR. This means that any of the
+    # RR methods that would typically be used: +mock+, +stub+, +verify+, etc. will be available to any
+    # setup, yeardown, helper, hookup, or assertion.
     class Situation < Riot::Situation
       include ::RR::Adapters::RRMethods
     end # Situation
 
+    # Binds the {Riot::Assertion} to RR so that successes and failures found by RR are inherently handled
+    # during an assertion evaluation. In effect, if RR suggests failure during validation, the assertion
+    # will fail and report these failures.
     class Assertion < Riot::Assertion
+      # Adds RR support to {Riot::Assertion#run}. The basic flow is to:
+      # * run the test as normal
+      # * ask RR to verify mock results
+      # * report any errors or return the result of the assertion as normal
+      # * reset RR so that the next assertion in the context can be verified cleanly.
+      #
+      # @param (see Riot::Assertion#run)
+      # @return (see Riot::Assertion#run)
       def run(situation)
         result = super
         situation.verify
@@ -19,14 +35,22 @@ module Riot
       end
     end # Assertion
 
-    module ContextHelpers
-    private
+    # Redefines the classes {Riot::Context} will use when creating new assertions and situations to be the
+    # ones provided RR support. See {Riot::RR::Assertion} and {Riot::RR::Situation}.
+    module ContextClassOverrides
+      # (see Riot::ContextClassOverrides#assertion_class)
       def assertion_class; Riot::RR::Assertion; end
+
+      # (see Riot::ContextClassOverrides#situation_class)
       def situation_class; Riot::RR::Situation; end
-    end # ContextHelpers
+    end # ContextClassOverrides
 
+    # A convenience method for telling {Riot::RR::ContextClassOverrides} to mix itself into {Riot::Context}.
+    # Thus, enabling RR support in Riot.
+    #
+    # @param [Class] context_class the class representing the Context to bind to
     def self.enable(context_class)
-      context_class.instance_eval { include Riot::RR::ContextHelpers }
+      context_class.instance_eval { include Riot::RR::ContextClassOverrides }
     end
 
   end # RR

data/lib/riot/runnable.rb

@@ -1,30 +1,83 @@
 module Riot
+  # A runnable block is pretty much an anonymous block decorator. It's goal is to accept a block, a
+  # description for what the block is intended to be for, and provide a +run+ method expects a
+  # {Riot::Situation} instance. Any time a {Riot::Situation} is provided to +run+, a {Riot::RunnableBlock}
+  # promises to evaluate itself against the situation in some way.
+  #
+  # Intent is to sub-class {Riot::RunnableBlock} with specific mechanisms for contorting the
+  # {Riot::Situation}.
   class RunnableBlock
+
+    # The decorated block.
     attr_reader :definition
+
+    # Creates a new RunnableBlock.
+    #
+    # @param [String] description a description of what this block is for
+    # @param [lambda] &definition the block to decorate
     def initialize(description, &definition)
       @description, @definition = description, definition || proc { false }
     end
 
+    # Given a {Riot::Situation}, eval the provided block against it and then return a status tuple.
+    # 
+    # @param [Riot::Situation] situation An instance of a {Riot::Situation}
+    # @return [Array<Symbol[, String]>] array containing at least an evaluation state
+    def run(situation)
+      raise "Define your own run"
+    end
+
+    # String representation of this block, which is basically the description.
+    #
+    # @return [String]
     def to_s; @description; end
   end # RunnableBlock
 
+  # Used to decorate a setup, hookup, a teardown or anything else that is about context administration.
   class Setup < RunnableBlock
     def initialize(&definition)
       super("setup", &definition)
     end
 
+    # Calls {Riot::Situation#setup} with the predefined block at {Riot::Context} run-time. Though this is 
+    # like every other kind of {Riot::RunnableBlock}, +run+ will not return a meaningful state, which means 
+    # the reporter will likely not report anything.
+    #
+    # @param [Riot::Situation] situation the situation for the current {Riot::Context} run
+    # @return [Array<Symbol>] array containing the evaluation state
     def run(situation)
       situation.setup(&definition)
       [:setup]
     end
   end # Setup
 
+  # Used to decorate a helper. A helper generally ends up being a glorified method that can be referenced 
+  # from within a setup, teardown, hookup, other helpers, assertion blocks, and assertion macro blocks; 
+  # basically anywhere the {Riot::Situation} instance is available.
+  #
+  #   context "Making dinner" do
+  #     helper(:easy_bake) do |thing|
+  #       EasyBake.new(thing, :ingredients => [:ketchup, :chocolate, :syrup])
+  #     end
+  #
+  #     setup do
+  #       easy_bake(:meatloaf)
+  #     end
+  #
+  #     asserts(:food_poisoning_probabilty).equals(0.947)
+  #   end # Making dinner
   class Helper < RunnableBlock
     def initialize(name, &definition)
       super("helper #{name}", &definition)
       @name = name
     end
 
+    # Calls {Riot::Situation#helper} with the predefined helper name and block at {Riot::Context} run-time. 
+    # Though this is like every other kind of {Riot::RunnableBlock}, +run+ will not return a meaningful 
+    # state, which means the reporter will likely not report anything.
+    #
+    # @param [Riot::Situation] situation the situation for the current {Riot::Context} run
+    # @return [Array<Symbol>] array containing the evaluation state
     def run(situation)
       situation.helper(@name, &definition)
       [:helper]

data/lib/riot/situation.rb

@@ -1,17 +1,62 @@
 module Riot
+  # A {Riot::Situation} is virtually a stack frame for a single context run. The intent is for all blocks to
+  # be evaluated against an instance of a Situation. Given the following superfluous context:
+  #
+  #   context "Foo" do # block-1
+  #
+  #     setup do # block-2
+  #       {:bar => "baz"}
+  #     end
+  #
+  #     asserts "its hash" do # block-3
+  #       topic
+  #     end.equals do # block-4
+  #       {:bar => "baz"}
+  #     end
+  #
+  #   end # Foo
+  #
+  # In this example, block-1 will be evaluated against a {Riot::Context} instance. Whereas block-2, block-3,
+  # and block-4 will all be evaluated against the same Situation instance. Situation instances (situations) 
+  # are bound to a single context run; they are not shared across context runs, regardless of their position
+  # in the test tree structure.
+  #
+  # What is gained from doing it this way is:
+  # * variables, methods, etc. set in one situation do not contaminate any others
+  # * variables, methods, etc. defined during a context run do not stick with the context itself
+  # * which means that testing state is independent of the test definitions themselves
   class Situation
+
+    # Returns the currrently tracked value of +topic+
+    #
+    # @return [Object] whatever the topic is currently set to
     def topic
       @_topic
     end
 
+    # This is where a setup block is actually evaluated and the +topic+ tracked.
+    #
+    # @param [lambda] &block a setup block
+    # @return [Object] the current topic value
     def setup(&block)
       @_topic = self.instance_eval(&block)
     end
 
+    # This is where a defined helper is born. A method is defined against the current instance of +self+.
+    # This method will not be defined on any other instances of Situation created afterwards.
+    #
+    # @param [Symbol, String] name the name of the helper being defined
+    # @param [lambda] &block the code to execute whennever the helper is called
     def helper(name, &block)
       (class << self; self; end).send(:define_method, name, &block)
     end
 
+    # Anonymously evaluates any block given to it against the current instance of +self+. This is how
+    # {Riot::Assertion assertion} and {Riot::AssertionMAcro assertion macro} blocks are evaluated,
+    # for instance.
+    #
+    # @param [lambda] &block the block to evaluate against +self+
+    # @return [Object] whatever the block would have returned
     def evaluate(&block)
       self.instance_eval(&block)
     end