riot 0.9.12 → 0.10.0

data/.gitignore

@@ -1,2 +1,3 @@
 *.gem
 pkg
+.*.swp

data/README.markdown

@@ -2,6 +2,11 @@
 
 An extremely fast, expressive, and context-driven unit-testing framework. Protest the slow test.
 
+When you're done reading here, take a gander at:
+
+* [Riot Rails](http://github.com/thumblemonks/riot_rails): Rails support for Riot testing. A definite work in progress (help welcomed). See [evoke-app](http://github.com/thumblemonks/evoke-app) for live examples.
+* [Riot.js](http://github.com/alexyoung/riotjs): for you JavaScript people, a version of Riot just for you. Both implementations will be informing the other. Lots of stuff to learn.
+
 #### Installation
 
 The Riot gem is hosted on gemcutter.org. It used to be hosted on GitHub, but they turned of gem support while moving to Rackspace, so we moved to gemcutter. If you have not already done so, add gemcutter.org to your list of gem sources like so:
@@ -17,32 +22,34 @@ Then, simply install the Riot gem like so:
 I have done a really simple benchmarking (10,000 runs), but right now, Riot is running about **2 times** faster than Test::unit and thusly Shoulda:
 
     Rehearsal ----------------------------------------------
-    Riot         0.620000   0.010000   0.630000 (  0.647318)
-    Test::Unit   1.500000   0.010000   1.510000 (  1.508144)
-    Shoulda      1.490000   0.000000   1.490000 (  1.501468)
-    ------------------------------------- total: 3.630000sec
+    Riot         0.360000   0.000000   0.360000 (  0.364236)
+    Test::Unit   1.250000   0.000000   1.250000 (  1.258466)
+    Shoulda      1.270000   0.010000   1.280000 (  1.277429)
+    ------------------------------------- total: 2.890000sec
 
                      user     system      total        real
-    Riot         0.630000   0.010000   0.640000 (  0.640481)
-    Test::Unit   1.460000   0.000000   1.460000 (  1.476454)
-    Shoulda      1.480000   0.010000   1.490000 (  1.490633)
+    Riot         0.360000   0.000000   0.360000 (  0.353360)
+    Test::Unit   1.260000   0.000000   1.260000 (  1.263777)
+    Shoulda      1.270000   0.000000   1.270000 (  1.270957)
 
 "Is it valid?", you ask. *I* think it is. I ain't no cheater, but I might be delusional.
 
 To compare against MiniTest, I had to run the benchmark separately.
 
     Rehearsal --------------------------------------------
-    Riot       0.630000   0.010000   0.640000 (  0.641285)
-    MiniTest   0.770000   0.070000   0.840000 (  0.846447)
-    ----------------------------------- total: 1.480000sec
+    Riot       0.350000   0.000000   0.350000 (  0.354331)
+    MiniTest   0.720000   0.070000   0.790000 (  0.793093)
+    ----------------------------------- total: 1.140000sec
 
                    user     system      total        real
-    Riot       0.630000   0.000000   0.630000 (  0.632337)
-    MiniTest   0.730000   0.070000   0.800000 (  0.798107)
+    Riot       0.350000   0.000000   0.350000 (  0.348796)
+    MiniTest   0.730000   0.060000   0.790000 (  0.801629)
+
+Riot is currently about twice as fast as minitest. Riot is also half the code of MiniTest (`310 loc < 674 loc` :)
 
-Riot is currently only slightly faster, but I haven't done any optimization yet. Riot is also half the code of MiniTest (`313 loc < 674 loc` :)
+All tests ran with `ruby 1.8.7 (2009-06-12 patchlevel 174) [i686-darwin9.8.0], MBARI 0x8770, Ruby Enterprise Edition 2009.10`.
 
-All tests ran with `ruby 1.8.7 (2009-06-12 patchlevel 174) [i686-darwin9]`.
+Riot also works very well with Ruby 1.9. The same benchmarks from above run through ruby-1.9 show Riot to be twice as fast as it is already. See our [benchmarks gist](http://gist.github.com/240353) for more details.
 
 ## Examples
 
@@ -50,7 +57,7 @@ All tests ran with `ruby 1.8.7 (2009-06-12 patchlevel 174) [i686-darwin9]`.
 
 **NOTE:** For no specific reason, I'm going to use an ActiveRecord model in the following examples.
 
-At it's very basic, Riot simply tries to assert that an expression is true or false. Riot does this through its `asserts` or `should` tests. An `asserts` test will pass if the result of running the test is neither `nil` or `false`. A `should` test does the exact same thing - they are in fact aliases. The only difference is in the way you write the assertion. 
+At it's very basic, Riot simply tries to assert that an expression is true or false. Riot does this through its `asserts` or `should` tests. An `asserts` test will pass if the result of running the test is neither `nil` or `false`. A `should` test does the exact same thing - they are in effect, aliases. The only difference is in the way you write the assertion. 
 
 For instance, given a test file named `foo_test.rb`, you might have the following code in it:
 
@@ -72,7 +79,7 @@ Notice that you do not define a class anywhere. That would be the entire content
 
 Sometimes it's more clear to say "this **should** be that" and sometimes it's better to say "**asserts** this is that". I promise you that Riot will get no more redundant than this, but also that besides speed, Riot will aim at being expressive with a minimal amount of syntax.
 
-The other important thing to note in the examples above is the use of the `topic`. Calling `topic` within any assertion will actually return the value of whatever was evaluated and returned from calling setup in the given context. In the examples above, `User.new` was returned, and is therefor accessible as the `topic`.
+The other important thing to note in the examples above is the use of the `topic`. Calling `topic` within any assertion will actually return the value of whatever was evaluated and returned from calling the last setup in the given context. In the examples above, `User.new` was returned, and is therefor accessible as the `topic`.
 
 I'm going to use `asserts` for the rest of this introduction, but you should know that you can replace any instance of `asserts` with `should` and nothing would change.
 
@@ -90,7 +97,7 @@ This is awfully redundant - not to mention, contrived. So, we wrote a shortcut t
 
     context "a billionaire" do
       setup { MoneyMaker.build(:billionaire) }
-      topic.kind_of(Billionaire)
+      asserts_topic.kind_of(Billionaire)
     end
 
 #### Example: Equality
@@ -104,7 +111,7 @@ For example:
       asserts("email address") { topic.email }.equals('foo@bar.com')
     end
 
-Here, you should begin to notice that tests themselves return the actual value. You do not write assertions into the test. Assertions are "aspected" onto the test. If the test above did not return 'foo@bar.com' for `@user.email`, the assertion would have failed.
+Here, you should begin to notice that tests themselves return the actual value. You do not write assertions into the test. Assertions are "aspected" onto the test. If the test above did not return 'foo@bar.com' for `topic.email`, the assertion would have failed.
 
 The `equals` modifier works with any type of value, including nil's. However, if you wanted to test for nil explicitly, you could simply do this:
 
@@ -265,7 +272,7 @@ I should say that I love Shoulda in theory and in practice. It changed the way I
 
 ### How Riot is different
 
-Riot differs primarily in that it does not rerun setup for each test in a context. I know this is going to shock and awe a lot of folks. However, over the past several years of my doing TDD in some capacity or another, there are certain habits I have tried to pick up on any many others I have tried to drop.
+Riot differs primarily in that it does not rerun setup for each test in a context. I know this is going to shock a lot of folks. However, over the past several years of my doing TDD in some capacity or another, there are certain habits I have tried to pick up on any many others I have tried to drop.
 
 For instance, I believe that no assertion should mangle the context of the test data it is running in. Following this allows me to require setup be run only once for a collection of related assertions. Even in a nested context where setups are inherited, the setup's are called only once per the specific context.
 
@@ -302,7 +309,7 @@ Basically, it's like setting up any other test runner. Then, from the command li
 Riot definitely works with the latest Sinatra. I personally use it to run tests for [Chicago](http://github.com/thumblemonks/chicago) and [Slvu](http://github.com/jaknowlden/slvu). Setup is pretty easy and very much like getting your tests to run with Test::Unit. In a test helper file that gets loaded into all of your tests (that need it), enter the following:
 
     require 'riot'
-    class Riot::Context
+    class Riot::Situation
       include Rack::Test::Methods
       def app; @app; end
     end
@@ -356,18 +363,19 @@ And then in your actual test, you might do the following:
 
 #### Assertion macros
 
-If you want to add special macros to an Assertion, this is as easy as adding them to a Context. Similar to Context macros, Assertion macros are included into the Assertion class.
+If you want to add special macros to an Assertion, this is as easy as adding them to a Context. Assertion macros, however, have a special mechanism for adding themselves onto an assertion. Thus, you will want to open the Riot::Assertion class and then define your assertion macro.
 
 For instance, let's say you wanted to add a macro for verifying that the result of an assertion is the same kind\_of object as you would expect. You would define the macro like so:
 
-    module Custom
-      module AssertionMacros
-        def kind_of(expected_class)
-          actual.kind_of?(expected) || fail("expected kind of #{expected}, not #{actual.inspect}")
+    module Riot
+      class Assertion
+
+        assertion(:kind_of) do |actual, expected|
+          actual.kind_of?(expected) ? pass : fail("expected kind of #{expected}, not #{actual.inspect}")
         end
-      end # AssertionMacros
-    end # Custom
-    Riot::Assertion.instance_eval { include Custom::AssertionMacros }
+
+      end # Assertion
+    end # Riot
 
 And in your context, you would use it like so:
 
@@ -375,20 +383,4 @@ And in your context, you would use it like so:
       asserts("a hash is defined") { {:foo => 'bar'} }.kind_of(Hash)
     end
 
-Notice in the new macro we defined the use of the magical **actual** variable. `actual` is evaluated when the assertion is defined and made available to any Assertion macro. If you think you might want to chain assertions checks together, know that only the last failure will get recorded.
-
-## TODO
-
-TONS OF STUFF
-
-1. Documentation about the `topic` method
-1. Better documentation for everything
-1. Refactor reporting; some abstracting is needed for recording a result (for instance)
-1. Need to know where in backtrace a test failed (line number, etc.); i.e. backtrace filtering for clarity
-1. More assertion macros: throws, etc.
-1. Aliases for context "with, without, when, ..."; add those words to test description
-1. Optimization and simplification (ex. flog is complaining print\_result\_stack)
-1. Better error messages?
-1. Perhaps: Multiple setup blocks in one context
-1. Perhaps: association macro chaining
-1. Perhaps: Uhhhhh ... a teardown method (only maybe. not sold :)
+If you think you might want to chain assertions checks together, this won't work out the box. The reason for this is that your assertion macro should call out to pass or fail, which each return a signal that will be used by the reporter. You could conceivably write an assertion as a filter macro instead, that would return `self`, but I can't decide why you would do that yet (in theory it would work, though).

data/VERSION

@@ -1 +1 @@
-0.9.12
+0.10.0

data/lib/riot.rb

@@ -1,28 +1,37 @@
-require 'riot/errors'
-require 'riot/report'
-require 'riot/situation'
+require 'riot/reporter'
 require 'riot/context'
-require 'riot/assertion'
+require 'riot/situation'
+require 'riot/runnable'
 require 'riot/assertion_macros'
 
 module Riot
+  def self.context(description, &definition)
+    root_contexts << Context.new(description, &definition)
+  end
 
-  # Configuration
+  def self.root_contexts; @root_contexts ||= []; end
 
-  def self.reporter; @reporter ||= (Riot.silently? ? NilReport.new : TextReport.new); end
-  def self.reporter=(report); @reporter = report; end
-  def self.silently!; @silently = true; end
-  def self.silently?; @silently || false; end
+  def self.run
+    the_reporter = reporter.new
+    the_reporter.summarize do
+      root_contexts.each { |ctx| ctx.run(the_reporter) }
+    end
+  end
+
+  def self.silently!; @silent = true; end
+  def self.silently?; @silent == true; end
+
+  def self.reporter
+    Riot.silently? ? Riot::SilentReporter : (@reporter_class || Riot::StoryReporter)
+  end
+  def self.reporter=(reporter_class) @reporter_class = reporter_class; end
+  def self.dots; Riot.reporter = Riot::DotMatrixReporter; end
 
-  at_exit do
-    Riot.reporter.results
-    exit false unless reporter.passed?
-  end unless Riot.silently?
+  at_exit { run unless Riot.silently? }
 end # Riot
 
-module Kernel
-  def context(description, reporter = nil, parent = nil, &block)
-    reporter ||= Riot.reporter
-    reporter.time { Riot::Context.new(description, reporter, parent, &block) }
+class Object
+  def context(description, &definition)
+    Riot.context(description, &definition)
   end
-end # Kernel
+end

data/lib/riot/assertion_macros.rb

@@ -1,17 +1,17 @@
 module Riot
-  module AssertionMacros
+  class Assertion
     # Asserts that the result of the test equals the expected value
     #   asserts("test") { "foo" }.equals("foo")
     #   should("test") { "foo" }.equals("foo")
-    def equals(expected)
-      expected == actual || fail("expected #{expected.inspect}, not #{actual.inspect}")
+    assertion(:equals) do |actual, expected|
+      expected == actual ? pass : fail("expected #{actual.inspect} to equal #{expected.inspect}")
     end
 
     # Asserts that the result of the test is nil
     #   asserts("test") { nil }.nil
     #   should("test") { nil }.nil
-    def nil
-      actual.nil? || fail("expected nil, not #{actual.inspect}")
+    assertion(:nil) do |actual|
+      actual.nil? ? pass : fail("expected nil, not #{actual.inspect}")
     end
 
     # Asserts that the result of the test is a non-nil value. This is useful in the case where you don't want
@@ -20,72 +20,82 @@ module Riot
     #   should("test") { 123 }.exists
     #   asserts("test") { "" }.exists
     #   asserts("test") { nil }.exists # This would fail
-    def exists
-      !actual.nil? || fail("expected a non-nil value")
+    assertion(:exists) do |actual|
+      !actual.nil? ? pass : fail("expected a non-nil value")
     end
 
-    # Asserts that the test raises the expected Exception
-    #   asserts("test") { raise My::Exception }.raises(My::Exception)
-    #   should("test") { raise My::Exception }.raises(My::Exception)
+    # Asserts that the result of the test is an object that is a kind of the expected type
+    #   asserts("test") { "foo" }.kind_of(String)
+    #   should("test") { "foo" }.kind_of(String)
+    assertion(:kind_of) do |actual, expected|
+      actual.kind_of?(expected) ? pass : fail("expected kind of #{expected}, not #{actual.inspect}")
+    end
+
+    # Asserts that an instance variable is defined for the result of the assertion. Value of instance
+    # variable is expected to not be nil
+    #   setup { User.new(:email => "foo@bar.baz") }
+    #   topic.assigns(:email)
     #
-    # You can also check to see if the provided message equals or matches your expectations. The message from
-    # the actual raised exception will be converted to a string before any comparison is executed.
-    #   asserts("test") { raise My::Exception, "Foo" }.raises(My::Exception, "Foo")
-    #   asserts("test") { raise My::Exception, "Foo Bar" }.raises(My::Exception, /Bar/)
-    #   asserts("test") { raise My::Exception, ["a", "b"] }.raises(My::Exception, "ab")
-    def raises(expected, expected_message=nil)
-      actual_error = raised && raised.original_exception
-      @raised = nil
-      if actual_error.nil?
-        return fail("should have raised #{expected}, but raised nothing")
-      elsif expected != actual_error.class
-        return fail("should have raised #{expected}, not #{actual_error.class}")
-      elsif expected_message && !(actual_error.message.to_s =~ %r[#{expected_message}])
-        return fail("expected #{expected_message} for message, not #{actual_error.message}")
+    # If a value is provided in addition to the variable name, the actual value of the instance variable
+    # must equal the expected value
+    #   setup { User.new(:email => "foo@bar.baz") }
+    #   topic.assigns(:email, "foo@bar.baz")
+    assertion(:assigns) do |actual, *expectings|
+      variable, expected_value = expectings
+      actual_value = actual.instance_variable_get("@#{variable}")
+      if actual_value.nil?
+        fail("expected @#{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}])
+      else
+        pass
       end
-      true
     end
 
     # Asserts that the result of the test equals matches against the proved expression
     #   asserts("test") { "12345" }.matches(/\d+/)
     #   should("test") { "12345" }.matches(/\d+/)
-    def matches(expected)
+    assertion(:matches) do |actual, expected|
       expected = %r[#{Regexp.escape(expected)}] if expected.kind_of?(String)
-      actual =~ expected || fail("expected #{expected.inspect} to match #{actual.inspect}")
-    end
-
-    # Asserts that the result of the test is an object that is a kind of the expected type
-    #   asserts("test") { "foo" }.kind_of(String)
-    #   should("test") { "foo" }.kind_of(String)
-    def kind_of(expected)
-      actual.kind_of?(expected) || fail("expected kind of #{expected}, not #{actual.inspect}")
+      actual =~ expected ? pass : fail("expected #{expected.inspect} to match #{actual.inspect}")
     end
 
     # Asserts that the result of the test is an object that responds to the given method
     #   asserts("test") { "foo" }.respond_to(:to_s)
     #   should("test") { "foo" }.respond_to(:to_s)
-    def respond_to(expected)
-      actual.respond_to?(expected) || fail("expected method #{expected.inspect} is not defined")
+    assertion(:respond_to) do |actual, expected|
+      actual.respond_to?(expected) ? pass : fail("expected method #{expected.inspect} is not defined")
     end
 
-    # Asserts that an instance variable is defined for the result of the assertion. Value of instance
-    # variable is expected to not be nil
-    #   setup { User.new(:email => "foo@bar.baz") }
-    #   topic.assigns(:email)
+    # Asserts that two arrays contain the same elements, the same number of times.
+    #   asserts("test") { ["foo", "bar"] }.same_elements(["bar", "foo"])
+    #   should("test") { ["foo", "bar"] }.same_elements(["bar", "foo"])
+    assertion(:same_elements) do |actual, expected|
+      require 'set'
+      same = (Set.new(expected) == Set.new(actual))
+      same ? pass : fail("expected elements #{expected.inspect} to match #{actual.inspect}")
+    end
+
+    # Asserts that the test raises the expected Exception
+    #   asserts("test") { raise My::Exception }.raises(My::Exception)
+    #   should("test") { raise My::Exception }.raises(My::Exception)
     #
-    # If a value is provided in addition to the variable name, the actual value of the instance variable
-    # must equal the expected value
-    #   setup { User.new(:email => "foo@bar.baz") }
-    #   topic.assigns(:email, "foo@bar.baz")
-    def assigns(variable, expected_value=nil)
-      actual_value = actual.instance_variable_get("@#{variable}")
-      return fail("expected @#{variable} to be assigned a value") if actual_value.nil?
-      unless expected_value.nil? || expected_value == actual_value
-        return fail(%Q[expected @#{variable} to be equal to '#{expected_value}', not '#{actual_value}'])
+    # You can also check to see if the provided message equals or matches your expectations. The message
+    # from the actual raised exception will be converted to a string before any comparison is executed.
+    #   asserts("test") { raise My::Exception, "Foo" }.raises(My::Exception, "Foo")
+    #   asserts("test") { raise My::Exception, "Foo Bar" }.raises(My::Exception, /Bar/)
+    assertion(:raises, expect_exception=true) do |actual_exception, expected_class, expected_message|
+      actual_message = actual_exception && actual_exception.message
+      if actual_exception.nil?
+        fail("should have raised #{expected_class}, but raised nothing")
+      elsif expected_class != actual_exception.class
+        fail("should have 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}")
+      else
+        pass
       end
-      true
     end
-  end # AssertionMacros
-end # Riot
 
-Riot::Assertion.instance_eval { include Riot::AssertionMacros }
+  end # Assertion
+end # Riot

data/lib/riot/context.rb

@@ -1,48 +1,38 @@
 module Riot
   class Context
-    # The protein
-    attr_reader :description, :assertions, :situation
-    def initialize(description, reporter, parent=nil, &context_block)
-      @description, @reporter, @parent = description, reporter, parent
-      @setups, @assertions = [], []
-      @situation = Situation.new
-      bootstrap(@situation)
-      instance_eval(&context_block) if block_given? # running the context
-      report
+    def initialize(description, setups=[], &definition)
+      @description = description
+      @contexts, @setups, @assertions = [], setups, []
+      self.instance_eval(&definition)
     end
-
-    # Walk it out. Call setup from parent first
-    def bootstrap(a_situation)
-      @parent.bootstrap(a_situation).each do |setup_block|
-        run_setup(a_situation, &setup_block)
-      end if @parent
-      @setups
-    end
-
-    def report
-      assertions.each { |assertion| @reporter.process_assertion(assertion) }
+    
+    def setup(&definition)
+      @setups << Setup.new(&definition)
     end
 
-    def to_s; @to_s ||= [@parent.to_s, @description].join(' ').strip; end
+    def asserts(what, &definition) new_assertion("asserts", what, &definition); end
+    def should(what, &definition) new_assertion("should", what, &definition); end
 
-    # DSLee stuff
+    def asserts_topic; asserts("topic") { topic }; end
 
-    def setup(&block)
-      @setups << block
-      run_setup(situation, &block)
+    def context(description, &definition)
+      # not liking the dup
+      @contexts << Context.new("#{@description} #{description}", @setups.dup, &definition)
     end
-
-    def context(description, &block) Context.new(description, @reporter, self, &block); end
-    def asserts(what, &block) add_assertion("asserts #{what}", &block); end
-    def should(what, &block) add_assertion("should #{what}", &block); end
-    def topic; asserts("topic") { topic }; end
-  private
-    def add_assertion(what, &block)
-      (assertions << Assertion.new("#{to_s} #{what}", @situation, &block)).last
+    
+    def run(reporter)
+      runnables = @setups + @assertions
+      reporter.describe_context(@description) unless @assertions.empty?
+      situation = Situation.new
+      runnables.each do |runnable|
+        reporter.report(runnable.to_s, runnable.run(situation))
+      end
+      @contexts.each { |ctx| ctx.run(reporter) }
+      reporter
     end
-
-    def run_setup(a_situation, &setup_block)
-      a_situation.topic = a_situation.instance_eval(&setup_block) if setup_block
+  private
+    def new_assertion(scope, what, &definition)
+      (@assertions << Assertion.new("#{scope} #{what}", &definition)).last
     end
   end # Context
 end # Riot