given 0.0.1

data/README.textile

@@ -0,0 +1,206 @@
+p{display=none}. <notextile><!-- -*- mode: textile; fill-column: 1000000; -*- --></notextile>
+
+h1. Thoughts on a new Ruby Specification Framework
+
+I've been playing aournd with some ideas for a new testing/specification framework for Ruby[1].  I've been trying to write down some of the motivation for this, but that's taking too long.  I just want to get some ideas down and published for review and we will address the whys and wherefores later.
+
+Essentially, I've been inspired by the Cucumber framework to bring the given/when/then style of specifications directly into unit tests.  So let's get right into it.
+
+h2. Status
+
+Given is now at a point where it is usable for small or experimental projects.  I would love for people to give it a try and see how it works out for them.  I wouldn't recommend it for anything mainstream yet because the details of the API are still subject to change.
+
+h2. Example Zero
+
+Here's the spec that I've been playing with.  Its gone through mulitple revisions and at least one prototype implementation.  And this is probably not the final form.
+
+With all that in mind, here's a specification in my imaginary framework:
+
+<pre>
+require 'given/test_unit'
+require 'examples/stack'
+
+class StackBehavior < Given::TestCase
+  Invariant { expect(@stack.depth) >= 0 }
+  Invariant { expect(@stack.empty?) == (@stack.depth == 0) }
+
+  Given(:empty_stack) do
+    Then { expect(@stack.depth) == 0 }
+
+    When { @stack.push(:an_item) }
+    Then { expect(@stack.depth) == 1 }
+    Then { expect(@stack.top) == :an_item }
+
+    When { @stack.pop }
+    FailsWith(Stack::UsageError)
+    Then { expect(exception.message) =~ /empty/ }
+  end
+
+  Given(:stack_with_two_items) {
+    Then { expect(@stack.top) == :top_item }
+    Then { expect(@stack.depth) == 2}
+
+    When { @result = @stack.pop }
+    Then { expect(@result) == :top_item }
+    Then { expect(@stack.top) == :bottom_item }
+    Then { expect(@stack.depth) == 1 }
+
+    When {
+      @stack.pop
+      @result = @stack.pop
+    }
+    Then { expect(@result) == :bottom_item }
+    Then { expect(@stack.depth) == 0 }
+  }
+
+  def empty_stack
+    @stack = Stack.new
+  end
+
+  def stack_with_two_items
+    empty_stack
+    @stack.push(:bottom_item)
+    @stack.push(:top_item)
+  end
+end
+</pre>
+
+Let's talk about the individual sections.
+
+h3. Given
+
+The _Given_ section specifies a starting point, a set of preconditions that must be true before the code under test is allowed to be run.  In standard test frameworks the preconditions are established with a combination of setup methods (or :before actions in RSpec) and code in the test.
+
+In the example code above, we see two starting points of interest.  One is an empty, just freshly created stack.  The other starting point is a stack with several items already push onto it.
+
+The setup methods are explicitly named by the given section.  The name of the setup method should be carefully named to provide the human reader the necessary information. 
+
+h3. When
+
+The _When_ section specifies the code to be tested ... oops, excuse me ... specified.  After the preconditions in the given section are met, the when code block is run.
+
+h3. Then
+
+The _Then_ sections are the postconditions of the specification. These then conditions must be true after the code under test (the _When_ block) is run.
+
+The code in the _Then_ block should be a single boolean condition that evaluates to true if the code in the _When_ block is correct.  If the _Then_ block evaluates to false, then that is recorded as a failure.
+
+h3. Invariant
+
+The _Invariant_ block is a new idea that doesn't have an analog in RSpec or Test::Unit.  The invariant allows you specify things that must always be true.  In the stack example, <tt>empty?</tt> is defined in term of <tt>size</tt>.  Whenever <tt>size</tt> is 0, <tt>empty?</tt> should be true.   Whenever <tt>size</tt> is non-zero, <tt>empty?</tt> should be false.
+
+You can conceptually think of an _Invariant_ block as a _Then_ block that automatically gets added to every _When_ within its scope.
+
+h2. Other Ideas
+
+That's the basics of what I'm trying to do.  Here are some more ideas.
+
+h3. Nesting Givens
+
+Although the example doesn't demonstrate this, I think the _Given_ blocks should be allowed to nest.  This is similar to the nested contexts in Shoulda or the nested describe blocks in RSpec.
+
+h3. Direct Code in Givens
+
+Since the block on a _Given_ section is used to scope the <em>When</em>'s and <em>Then</em>s, it can't be used to directly specify the setup code.  That's why we put the setup code in a named method and pass the name of the method to the _Given_.  I actually like the way that reads, but also am wondering if there is a way to allow direct code as well.
+
+Here's one idea:
+
+<pre>
+  Given(Setup { @stack = Stack.new }) do
+    When { ... }
+    Then { ... }
+  end
+</pre>
+
+Here's another idea:
+
+<pre>
+  Given { @stack = Stack.new }.and do
+    When { ... }
+    Then { ... }
+  end
+</pre>
+
+I think both options are ugly.
+
+h2. Recent Changes
+
+h3. Contract/Behavior -> TestCase
+
+I've been playing with the idea of calling the containing classes either Give::Behavior or Given::Contract.  I like the name Contract.  And while the pre/post condition thing is very close to the idea of contracts, its not quite the same thing.  Behavior comes close to describing the idea in my head, but I'm not overly fond of the word itself.
+
+So finally, I just tossed both ideas and just went with Given::TestCase.  The first implementation of Given is on top of Test::Unit, and we allow Test::Unit style test_xxx methods in the class, so there's no need to hide it.
+
+h3. Expectations
+
+I really like the idea of being able to just say:
+
+<pre>
+  Then { @result == 1 }
+</pre>
+
+and have that raw ruby code be the expectation for the specification.  Unfortunately, that has two drawbacks when I got down into the nitty gritty details.
+
+# It just returns a boolean value.  So when the expectation fails, all the reporting software can to is just say the expectation failed.  It can't give any details about why the expectation failed.
+# The second problem is another reporting problem.  When the Then block returns false an AssertionFailed error will be thrown and handled by the test running software.  Unfortunately the error is thrown from a point in the stack after the Then code block has completed running, therefore the source code location of the offending Then block is no longer in the stack trace.  
+
+Both of these problems can be solved if the AssertionFailed error was thrown while the Then block was still active.  So how do we accomplish that?
+
+h4. Idea #1 -- Use assert_xxx
+
+We could just code the assert_equal (and related assert_xxx functions) explicitly in the Then block.
+
+<pre>
+  Then { assert_equal 1, @result }
+</pre>
+
+This will actually almost work with no changes.  Only one small problem, assert_xxx methods do not necessarily return true if the assertion passed.  Therefore, the assert can pass, but the Then will fail because assert_equal returns nil.
+
+I imagine I might have to give up that particular behavior of Then blocks, but I'm not ready to yet.
+
+The bigger problem is that it is just too ugly.  I'm afraid people will be tempted to put multiple asserts in a single Then, something I'm trying to discourage.
+
+h4. Idea #2 -- Use RSpec-like Syntax
+
+We could just use RSpec like syntax in the Then block:
+
+<pre>
+  Then { @result.should == 1 }
+</pre>
+
+In fact, the Matchy library will allow us to use the .should notation in test unit.  It should work for Given as well.  There is one minor problem with this and one philosophical problem.  The minor problem is that like assert_xxx, the Matchy .should methods return non-true if the assertion passes.
+
+The philosophical problem is that I really dislike polluting Object's namespace dropping a should method into every object.  It just rubs me the wrong way.
+
+h4. Idea #3 -- ParseTree
+
+This suggestion falls in the category of bizzare and weird.  Why not use ParseTree to get the s-expression of the Ruby code in the Then block and parse out the individual pieces of the code and find whatever it needs for the error messages.
+
+Althought the idea sounds cool, it also sounds really fragile.  ParseTree pulls out the internal parse tree generated by the Ruby runtime, and that internal data structure has been known to change between version.  Also, ParseTree doesn't run under JRuby so we would be artificially limiting the usefulness of the Given library.  No, this idea doesn't even get off the ground.
+
+h4. Idea #4 -- Redefine operators
+
+We could redefine operators like == throw exceptions at the appropriate times. This would allow the Then blocks to remain simple Ruby expressions.  There are multiple problems with this:
+
+# The operator redefinitions would have to be applied at the beginning of the block and removed after the block was done.  Although doable, this seems like a lot of definition churn.
+# The operator redefinitions should only apply at the top level of the expression.  Currenly, I have no idea of how to accomplish this.
+# Since operators have different definitions for each class, the operators would have to be redefined for all classes.
+# This only addresses expressions with an operator at the top level.  It still doesn't handle expressions like: <code>Then { @result.nil? }</code>.
+
+h4. Idea #5 -- expect()
+
+Here's idea stolen from one of the Javascript testing libraries.  If we wrap the item we are making assertions about in a method, we can have that method return an expectation object that properly responds to operators and queries.  If we name that object properly, then we should a nicely readable syntax too.  Something like this:
+
+<pre>
+  Then { expect(@result) == 1 }
+  Then { expect(@result).nil? }
+</pre>
+
+Technically, this is equivalent to the RSpec/Should solution, but without polluting the global object namespace.  And it reads almost as well.  I think I like this.
+
+h2. Summary
+
+Feel free to comment on the ideas here.  Eventually I hope to have a working prototype.
+
+<hr>
+fn1. Right, like Ruby doesn't have enough of them.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rake/clean'
+require 'rake/testtask'
+
+CLOBBER.include("html")
+
+task :default => ["test:units", "test:functionals"]
+
+task :tu => "test:units"
+task :tf => "test:functionals"
+
+EXAMPLE_FILES = FileList['examples/*_behavior.rb']
+desc "Run Examples"
+task :examples do
+  ruby "-I.:lib #{EXAMPLE_FILES}"
+end
+
+# README Formatting --------------------------------------------------
+
+require 'redcloth'
+
+directory 'html'
+
+desc "Display the README file"
+task :readme => "html/README.html" do
+  sh "open html/README.html"
+end
+
+desc "format the README file"
+task "html/README.html" => ['html', 'README.textile'] do
+  open("README.textile") do |source|
+    open('html/README.html', 'w') do |out|
+      out.write(RedCloth.new(source.read).to_html)
+    end
+  end
+end

data/examples/stack.rb

@@ -0,0 +1,29 @@
+class Stack
+  class UsageError < RuntimeError
+  end
+
+  def initialize
+    @items = []
+  end
+
+  def depth
+    @items.size
+  end
+
+  def empty?
+    @items.size == 0
+  end
+
+  def top
+    @items.last
+  end
+
+  def push(item)
+    @items.push(item)
+  end
+
+  def pop
+    fail UsageError, "Cannot pop an empty stack" if empty?
+    @items.pop
+  end
+end

data/examples/stack_test.rb

@@ -0,0 +1,46 @@
+require 'given/test_unit'
+require 'examples/stack'
+
+class StackBehavior < Given::TestCase
+  Invariant { expect(@stack.depth) >= 0 }
+  Invariant { expect(@stack.empty?) == (@stack.depth == 0) }
+
+  Given(:empty_stack) do
+    Then { expect(@stack.depth) == 0 }
+
+    When { @stack.push(:an_item) }
+    Then { expect(@stack.depth) == 1 }
+    Then { expect(@stack.top) == :an_item }
+
+    When { @stack.pop }
+    FailsWith(Stack::UsageError)
+    Then { expect(exception.message) =~ /empty/ }
+  end
+
+  Given(:stack_with_two_items) {
+    Then { expect(@stack.top) == :top_item }
+    Then { expect(@stack.depth) == 2}
+
+    When { @result = @stack.pop }
+    Then { expect(@result) == :top_item }
+    Then { expect(@stack.top) == :bottom_item }
+    Then { expect(@stack.depth) == 1 }
+
+    When {
+      @stack.pop
+      @result = @stack.pop
+    }
+    Then { expect(@result) == :bottom_item }
+    Then { expect(@stack.depth) == 0 }
+  }
+
+  def empty_stack
+    @stack = Stack.new
+  end
+
+  def stack_with_two_items
+    empty_stack
+    @stack.push(:bottom_item)
+    @stack.push(:top_item)
+  end
+end

data/lib/given.rb

@@ -0,0 +1,6 @@
+module Given
+end
+
+require 'given/errors'
+require 'given/dsl'
+require 'given/expectation'

data/lib/given/anonymous_code.rb

@@ -0,0 +1,22 @@
+module Given
+  class AnonymousCode
+    def initialize(block)
+      @block = block
+    end
+    
+    def run(context)
+      context.instance_eval(&@block)
+    end
+
+    def line_marker
+      nil
+    end
+
+    def file_line
+      nil
+    end
+  end
+
+  DO_NOTHING = AnonymousCode.new(lambda { })
+  TRUE_CODE  = AnonymousCode.new(lambda { true })
+end

data/lib/given/code.rb

@@ -0,0 +1,20 @@
+require 'given/anonymous_code'
+
+module Given
+  class Code < AnonymousCode
+    def initialize(mark, block)
+      @mark = mark
+      super(block)
+    end
+
+    def line_marker
+      "%s%d" % [@mark, eval("__LINE__", @block)]
+    end
+
+    def file_line
+      file = eval("__FILE__", @block)
+      line = eval("__LINE__", @block)
+      "#{file}:#{line}"
+    end
+  end
+end

data/lib/given/dsl.rb

@@ -0,0 +1,114 @@
+require 'given/anonymous_code'
+require 'given/code'
+
+module Given
+  module DSL
+    module TestHelper
+      def exception
+        @_given_exception
+      end
+
+      def given_check(ok, msg, args)
+        given_failure(msg % args) if ! ok
+        true
+      end
+
+      def expect(value)
+        Given::Expectation.new(value, self)
+      end
+    end
+
+    private
+
+    def Given(*args, &block)
+      _given_levels.push(Code.new('G', block))
+      @_given_setup_codes ||= []
+      @_given_invariant_codes ||= []
+      @_given_when_code = DO_NOTHING
+      @_given_exception_class = nil
+      old_setups = @_given_setup_codes
+      old_invariants = @_given_invariant_codes
+      @_given_setup_codes += args
+      yield
+    ensure
+      @_given_setup_codes = old_setups
+      @_given_invariant_codes = old_invariants
+      @_given_when_code = DO_NOTHING
+      _given_levels.pop
+    end
+
+    def When(&when_code)
+      _given_must_have_context("When")
+      @_given_when_code = Code.new('W', when_code)
+      @_given_exception_class = nil
+    end
+
+    def Then(&then_code)
+      _given_must_have_context("Then")
+      _given_make_test_method("Then", Code.new('T', then_code), @_given_exception_class)
+    end
+    alias And Then
+
+    def FailsWith(exception_class, &fail_code)
+      _given_must_have_context("FailsWith")
+      @_given_exception_class = exception_class
+      _given_make_test_method("FailsWith", TRUE_CODE, exception_class)
+      fail_code.call if fail_code
+    end
+
+    def Invariant(&block)
+      @_given_invariant_codes ||= []
+      @_given_invariant_codes += [Code.new('I', block)]
+    end
+
+    # Internal Use Methods -------------------------------------------
+
+    def _given_levels
+      @_given_levels ||= []
+    end
+
+    def _given_must_have_context(clause)
+      fail UsageError, "A #{clause} clause must be inside a given block" if
+        _given_levels.size <= 0
+    end
+
+    def _given_test_name(setup_codes, when_code, then_code)
+      tags = _given_levels.map { |code| code.line_marker }
+      tags << when_code.line_marker
+      if then_code
+        tags << then_code.line_marker
+      end
+      tags.compact!
+      sort = "%05d" % tags.last[1..-1].to_i
+      "test__#{sort}_#{tags.join('_')}_"
+    end
+
+    def _given_make_test_method(clause, then_code, exception_class)
+      setup_codes = @_given_setup_codes
+      when_code = @_given_when_code
+      invariant_codes = @_given_invariant_codes
+      define_method _given_test_name(setup_codes, when_code, then_code) do
+        setup_codes.each do |s| send s end
+        if exception_class.nil?
+          when_code.run(self)
+        else
+          begin
+            when_code.run(self)
+            given_failure("Expected #{exception_class} Exception", when_code)
+          rescue exception_class => ex
+            @_given_exception = ex
+          rescue Exception => ex
+            @_given_exception = ex
+            given_failure("Expected #{exception_class} Exception, " +
+              "but got #{exception.class}",
+              when_code)
+          end
+        end
+        given_assert(clause, then_code)
+        invariant_codes.each do |inv|
+          given_assert("Invariant", inv)
+        end
+      end
+    end
+  end
+end