riot 0.12.1 → 0.12.2

data/lib/riot/context_options.rb

@@ -7,18 +7,28 @@ module Riot
     #   context "Foo" do
     #     set :transactional, true
     #   end
-    def set(key, value) options[key] = value; end
+    #
+    # @param [Object] key the key used to look up the option value later
+    # @param [Object] value the option value to store
+    def set(key, value)
+      options[key] = value
+    end
 
     # Returns the value of a set option. The key must match exactly, symbols and strings are not
     # interchangeable.
     #
+    # @param [Object] key the key used to look up the option value
     # @return [Object]
-    def option(key) options[key]; end
+    def option(key)
+      options[key]
+    end
 
-    # Returns the has of defined options.
+    # Returns the hash of defined options.
     #
     # @return [Hash]
-    def options; @options ||= {}; end
+    def options
+      @options ||= {}
+    end
 
   end # ContextOptions
 end # Riot

data/lib/riot/message.rb

@@ -3,21 +3,102 @@ class BlankSlate
 end
 
 module Riot
+  # A Message is similar in nature (but not implementation) to a string buffer; you put some strings in and
+  # calling {#to_s} will generate a single new string. What's special abnout Message is how you get strings
+  # into it. By convention, any method called on a Message that isn't defined will have its name turned into
+  # a string and any underscores replaced with spaces. This happens for each method call and those small
+  # messages are chained together at the end. For instance:
+  #
+  #   message = Riot::Message.new
+  #   message.hello_world.to_s
+  #    => "hello world"
+  #   
+  #   message.whats_the_news.to_s
+  #    => "hello world whats the news"
+  #
+  # For every method called it is also acceptable to pass any number of arguments. These arguments will be
+  # added to the final message after having {Kernel#inspect} called on them. Another for instance:
+  #
+  #   message = Riot::Message.new
+  #   message.expected([1, 2, 3], "foo").not([3, 2, 1], "bar")
+  #   message.to_s
+  #    => 'expected [1, 2, 3], "foo", not [3, 2, 1], "bar"'
+  #
+  # This is useful for - and was originally intended for - generating pass/fail messages from
+  # {Riot::AssertionMacro assertion macros}.
   class Message < BlankSlate
+
+    # Creates a new Message instance.
+    #
+    # @param [Array<Object>] *phrases an array of objects to be inspected
     def initialize(*phrases)
-      @chunks = []; _inspect(phrases)
+      @chunks = []
+      _inspect(phrases)
     end
 
+    # Generates the string value of the built-up message.
+    #
+    # @return [String]
     def to_s; @chunks.join.strip; end
+    alias_method :inspect, :to_s
+
+    # Converts any method call into a more readable string by replacing underscores with spaces. Any
+    # arguments to the method are inspected and appended to the final message. Blocks are currently ignored.
+    #
+    # @param [String, Symbol] meth the method name to be converted into a more readable form
+    # @param [Array<Object>] *phrases an array of objects to be inspected
+    # @return [Riot::Message] this instance for use in chaining calls
+    def method_missing(meth, *phrases, &block)
+      push(meth.to_s.gsub('_', ' '))
+      _inspect(phrases)
+    end
 
-    def method_missing(meth, *phrases, &blk) push(meth.to_s.gsub('_', ' ')); _inspect(phrases); end
+    # Adds a comma then the provided phrase to this message.
+    #
+    #   Riot::Message.new.hello.comma("world").to_s
+    #    => "hello, world"
+    #
+    # @param [String] str any string phrase to be added after the comma
+    # @param [Array<Object>] *phrases an array of objects to be inspected
+    # @return [Riot::Message] this instance for use in chaining calls
+    def comma(str, *phrases)
+      _concat([", ", str])
+      _inspect(phrases)
+    end
 
-    def comma(str, *phrases) _concat([", ", str]); _inspect(phrases); end
+    # Adds the string ", but".
+    #
+    #   Riot::Message.new.any_number.but(52).to_s
+    #    => "any number, but 52"
+    #
+    # @param [Array<Object>] *phrases an array of objects to be inspected
+    # @return [Riot::Message] this instance for use in chaining calls
     def but(*phrases); comma("but", *phrases); end
+
+    # Adds the string ", not".
+    #
+    #   Riot::Message.new.expected_freebies.not("$1.50").to_s
+    #    => 'expected freebies, not "$1.50"'
+    #
+    # @param [Array<Object>] *phrases an array of objects to be inspected
+    # @return [Riot::Message] this instance for use in chaining calls
     def not(*phrases); comma("not", *phrases); end
-    def push(str) _concat([" ", str]); end
+
   private
-    def _concat(chunks) @chunks.concat(chunks); self; end
-    def _inspect(phrases) phrases.each { |phrase| push(phrase.inspect) }; self; end
+    def push(str)
+      _concat([" ", str])
+    end
+
+    def _concat(chunks)
+      @chunks.concat(chunks)
+      self
+    end
+
+    def _inspect(phrases)
+      unless phrases.empty?
+        push(phrases.map { |phrase| phrase.inspect }.join(", "))
+      end
+      self
+    end
   end # Message
 end # Riot

data/lib/riot/middleware.rb

@@ -1,5 +1,60 @@
 module Riot
 
+  # Context middlewares are chainable, context preparers. This to say that a middleware knows about a single
+  # neighbor and that it can prepare context before the context is "run". As a for instance, suppose you
+  # wanted the following to be possible.
+  # 
+  #   context Person do
+  #     denies(:valid?)
+  #   end # Person
+  # 
+  # Without writing a middleware, the topic in this would actually be nil, but what the context is saying is 
+  # that there should be something in the topic that responds to +:valid?+; an instance of +Person+ in this 
+  # case. We can do this with middleware like so:
+  # 
+  #   class Modelware < Riot::ContextMiddleware
+  #     register
+  #   
+  #     def call(context)
+  #       if context.description.kind_of?(Model)
+  #         context.setup { context.description.new }
+  #       end
+  #       middleware.call(context)
+  #     end
+  #   end # Modelware
+  # 
+  # That's good stuff. If you're familiar at all with the nature of Rack middleware - how to implement it, 
+  # how it's executed, etc. - you'll be familiar with Context middleware as the principles are similar:
+  # 
+  # 1. Define a class that extends {Riot::ContextMiddleware}
+  # 2. Call +register+
+  # 3. Implement a +call+ method that accepts the Context that is about to be executed
+  # 4. Do stuff, but make sure to pass the call along with +middleware.call(context)+
+  # 
+  # Steps 1, 2, and 3 should be pretty straight-forward. Currently, +context+ is the only argument to +call+.
+  # When your middleware is initialized it is given the next registered middleware in the chain (which is
+  # where the `middleware` method gets its value from).
+  # 
+  # So, "Do stuff" from step 4 is the where we start breaking things down. What can you actually do? Well,
+  # you can do anything to the context that you could do if you were writing a Riot test; and I do mean
+  # anything.
+  # 
+  # * Add setup blocks (as many as you like)
+  # * Add teardown blocks (as many as you like)
+  # * Add hookup blocks (as many as you like)
+  # * Add helpers (as many as you like)
+  # * Add assertions
+  # 
+  # The context in question will not run before all middleware have been applied to the context; this is
+  # different behavior than that of Rack middleware. {Riot::ContextMiddleware} is only about preparing a 
+  # context, not about executing it. Thus, where in your method you actually pass the call off to the next 
+  # middleware in the chain has impact on how the context is set up. Basically, whatever you do before 
+  # calling `middleware.call(context)` is done before any other middleware gets setup and before the innards 
+  # of the context itself are applied. Whatever you do after that call is done after all that, but still 
+  # before the actual setups, hookups, assertions, and teardowns are run.
+  # 
+  # Do not expect the same instance of middleware to exist from one {Riot::Context} instance to the next. It
+  # is highly likely that each {Riot::Context} will instantiate their own middleware instances.
   class ContextMiddleware
     # Registers the current middleware class with Riot so that it may be included in the set of middlewares
     # Riot will poke before executing a Context.
@@ -12,16 +67,25 @@ module Riot
     #       context.hookup { ... }
     #     end
     #   end
-    def self.register; Context.middlewares << self; end
+    def self.register
+      Context.middlewares << self
+    end
 
-    attr_reader :middleware # Theoretically, the next middleware in the stack
+    # Theoretically, the next middleware in the stack
+    attr_reader :middleware
 
+    # Create a new middleware instance and give it the next middleware in the chain.
+    #
+    # @param [Riot::ContextMiddleware] middleware the next middleware instance in the chain
     def initialize(middleware)
       @middleware = middleware
     end
 
-    # The meat. Because you have access to the Context, you can add your own setups,
-    # hookups, etc. +call+ will be called before any tests are run, but after the Context is configured.
+    # The magic happens here. Because you have access to the Context, you can add your own setups, hookups,
+    # etc. +call+ will be called before any tests are run, but after the Context is configured. Though 
+    # something will likely be returned, do not put any faith in what that will be.
+    #
+    # @param [Riot::Context] context the Context instance that will be prepared by registered middleware
     def call(context)
       raise "You should implement call yourself"
     end
@@ -34,6 +98,7 @@ module Riot
       @context_definition = context_definition
     end
 
+    # (see Riot::ContextMiddleware#call)
     def call(context) context.instance_eval(&@context_definition); end
   end # AllImportantMiddleware
 

data/lib/riot/reporter.rb

@@ -1,7 +1,27 @@
 module Riot
+
+  # A Reporter decides how to output the result of a test. When a context is set to be executed, the
+  # {Riot::Reporter#describe_context} method is called with the context that will be running; this remains
+  # so until the next context is executed. After each {Riot#Assertion#evaluate assertion is evaluated}, 
+  # {Riot::Reporter#report} is called with the description of the assertion and the resulting response.
+  #
+  # The general idea is that a sub-class of Reporter should be defined that knows specifically how to
+  # output the reported results. In the sub-class, you simply need to implement a +pass+, +fail+, +error+,
+  # and +results+ method.
   class Reporter
-    attr_accessor :passes, :failures, :errors, :current_context
+    # Count of successful assertions so far
+    attr_accessor :passes
+
+    # Count of failed assertions so far
+    attr_accessor :failures
+
+    # Count of errored assertions so far
+    attr_accessor :errors
 
+    # The context that is currently being reported on
+    attr_accessor :current_context
+
+    # Creates a new Reporter instance and initializes counts to zero
     def initialize
       @passes = @failures = @errors = 0
       @current_context = ""
@@ -9,8 +29,17 @@ module Riot
 
     def new(*args, &block); self; end
 
-    def success?; (@failures + @errors) == 0; end
+    # Returns true if no failures or errors have been produced yet.
+    #
+    # @return [Boolean]
+    def success?
+      (@failures + @errors) == 0
+    end
 
+    # Starts a timer, execute the provided block, then reports the results. Useful for timing context
+    # execution(s).
+    #
+    # @param [lambda] &block the contexts to run
     def summarize(&block)
       started = Time.now
       yield
@@ -18,8 +47,18 @@ module Riot
       results(Time.now - started)
     end
 
-    def describe_context(context); @current_context = context; end
+    # Called when a new context is about to execute to set the state for this Reporter instance.
+    #
+    # @param [Riot::Context] context the context that is about to execute
+    def describe_context(context)
+      @current_context = context
+    end
 
+    # Called immediately after an assertion has been evaluated. From this method either +pass+, +fail+,
+    # or +error+ will be called.
+    #
+    # @param [String] description the description of the assertion
+    # @param [Array<Symbol, *[Object]>] response the evaluation response from the assertion
     def report(description, response)
       code, result = *response
       case code
@@ -36,120 +75,42 @@ module Riot
       end
     end
 
-    def pass(description, result); end
-    def fail(description, message, line, file); end
-    def error(description, result); end
-  end # Reporter
-
-  class IOReporter < Reporter
-    def initialize(writer=STDOUT)
-      super()
-      @writer = writer
-    end
-    def puts(message) @writer.puts(message); end
-    def print(message) @writer.print(message); end
-
-    def line_info(line, file)
-      line ? "(on line #{line} in #{file})" : ""
-    end
-
-    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
-
-    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
-
-  protected
-    def filter_backtrace(backtrace)
-      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
-
-      cleansed.empty?? backtrace : cleansed
-    end
-
-    begin
-      raise LoadError if ENV["TM_MODE"]
-      require 'rubygems'
-      require 'term/ansicolor'
-      include Term::ANSIColor
-    rescue LoadError
-      def green(str); str; end
-      alias :red :green
-      alias :yellow :green
+    # Called if the assertion passed.
+    #
+    # @param [String] description the description of the assertion
+    # @param [Array<Symbol, String]>] result the evaluation response from the assertion
+    def pass(description, result)
+      raise "Implement this in a sub-class"
     end
-  end
-
-  class StoryReporter < IOReporter
-    def describe_context(context)
-      super
-      puts context.detailed_description
-    end
-    def pass(description, message) puts "  + " + green("#{description} #{message}".strip); end
 
+    # Called if the assertion failed.
+    #
+    # @param [String] description the description of the assertion
+    # @param [Array<Symbol, String, Number, String]>] response the evaluation response from the assertion
     def fail(description, message, line, file)
-      puts "  - " + yellow("#{description}: #{message} #{line_info(line, file)}".strip)
+      raise "Implement this in a sub-class"
     end
 
-    def error(description, e) puts "  ! " + red("#{description}: #{e.message}"); end
-  end
-
-  class VerboseStoryReporter < StoryReporter
-    def error(description, e)
-      super
-      puts red(format_error(e))
-    end
-  end
-
-  class DotMatrixReporter < IOReporter
-    def initialize(writer=STDOUT)
-      super
-      @details = []
-    end
-
-    def pass(description, message)
-      print green(".")
-    end
-
-    def fail(description, message, line, file)
-      print yellow("F")
-      @details << "FAILURE - #{test_detail(description, message)} #{line_info(line, file)}".strip
-    end
-
-    def error(description, e)
-      print red("E")
-      @details << "ERROR - #{test_detail(description, format_error(e))}"
+    # Called if the assertion had an unexpected error.
+    #
+    # @param [String] description the description of the assertion
+    # @param [Array<Symbol, Exception]>] result the exception from the assertion
+    def error(description, result)
+      raise "Implement this in a sub-class"
     end
 
+    # Called after all contexts have finished. This is where the final results can be output.
+    #
+    # @param [Number] time_taken number of seconds taken to run everything
     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}"
+      raise "Implement this in a sub-class"
     end
-  end
-
-  class SilentReporter < Reporter
-    def pass(description, message); end
-    def fail(description, message, line, file); end
-    def error(description, e); end
-    def results(time_taken); end
-  end
+  end # Reporter
+
 end # Riot
+
+require 'riot/reporter/silent'
+require 'riot/reporter/io'
+require 'riot/reporter/story'
+require 'riot/reporter/dot_matrix'
+require 'riot/reporter/pretty_dot_matrix'