lemon 0.8.4 → 0.8.5

data/lib/lemon/cli.rb

@@ -61,7 +61,7 @@ module Lemon
     def test(scripts)
       require 'lemon/controller/test_runner'
 
-      loadpath = options[:loadpath] || []
+      loadpath = options[:loadpath] || ['lib']  # + ['lib'] ?
       requires = options[:requires] || []
 
       loadpath.each{ |path| $LOAD_PATH.unshift(path) }
@@ -74,7 +74,9 @@ module Lemon
         scripts, :format=>options[:format], :namespaces=>options[:namespaces]
       )
 
-      runner.run
+      success = runner.run
+
+      exit -1 unless success
     end
 
     #

data/lib/lemon/controller/test_runner.rb

@@ -77,6 +77,9 @@ module Lemon
     end
 
     # Run tests.
+    #
+    # @return [Boolean] 
+    #   Whether tests ran without error or failure.
     def run
       #prepare
       report.start_suite(suite)
@@ -128,6 +131,7 @@ module Lemon
         report.finish_case(testcase)
       end
       report.finish_suite(suite) #(successes, failures, errors, pendings)
+      return record[:error].size + record[:fail].size > 0 ? false : true
     end
 
     # Iterate over suite testcases, filtering out unselected testcases

data/lib/lemon/model/test_case.rb

@@ -21,11 +21,11 @@ module Lemon
     # Ordered list of testunits.
     attr :units
 
-    # Before any test case units are run.
+    # Before matching test units.
     attr :before
     #attr_accessor :prepare
 
-    # After all test case units are run.
+    # After matching test units.
     attr :after
     #attr_accessor :cleanup
 
@@ -88,6 +88,12 @@ module Lemon
       end
 
       # Define a unit test for this case.
+      #
+      # @example
+      #   unit :puts => "print message with new line to stdout" do
+      #     puts "Hello"
+      #   end
+      #
       def unit(*target, &block)
         target = target.map{ |x| Hash === x ? x.to_a : x }.flatten
         method, aspect = *target
@@ -138,10 +144,15 @@ module Lemon
       end
       alias_method :omit, :Omit
 
+      # Setup is used to set things up for each unit test.
+      # The setup procedure is run before each unit.
       #
-      def setup(description=nil, &block)
-        if block
-          context  = TestContext.new(@testcase, description, &block)
+      # @param [String] description
+      #   A brief description of what the setup procedure sets-up.
+      #
+      def setup(description=nil, &procedure)
+        if procedure
+          context  = TestContext.new(@testcase, description, &procedure)
           @context = context
           #@function = false
           #@testcase.steps << context
@@ -150,60 +161,131 @@ module Lemon
       alias_method :Setup, :setup
       alias_method :Concern, :setup
       alias_method :concern, :setup
+
+      # @deprecate This alias will probably not stick around.
       alias_method :Context, :setup
       alias_method :context, :setup
 
+=begin
+      # TODO: Currently there is no difference between Setup, Instance and Singleton
+
       ## Define a new test instance for this case.
-      #def instance(description=nil, &block)
-      #  context  = TestInstance.new(@testcase, description, &block)
-      #  @context = context
-      #  @function = false
-      #  #@testcase.steps << context
-      #end
-      #alias_method :Instance, :instance
+      def instance(description=nil, &block)
+        if block
+          #context = TestInstance.new(@testcase, description, &block)
+          context = TestContext.new(@testcase, description, &block)
+        else
+          context = TestContext.new(@testcase, description) do
+                      @testcase.target.new  # No arguments!!!
+                    end
+        end
+        @context = context
+        #@function = false
+        #@testcase.steps << context
+      end
+      alias_method :Instance, :instance
 
       # Define a new test singleton for this case.
-      #def Singleton(description=nil, &block)
-      #  context  = TestSingleton.new(@testcase, description, &block)
-      #  @context = context
-      #  @function = true
-      #  #@testcase.steps << context
-      #end
-      #alias_method :singleton, :Singleton
+      def Singleton(description=nil, &block)
+        if block
+          #context = TestSingleton.new(@testcase, description, &block)
+          context = TestContext.new(@testcase, description, &block)
+        else
+          context = TestContext.new(@testcase, description){ @testcase.target }
+        end
+        @context = context
+        #@function = true
+        #@testcase.steps << context
+      end
+      alias_method :singleton, :Singleton
+=end
 
-      def teardown(&block)
-        @context.teardown = block
+      # Teardown procedure is used to clean-up after each unit test. 
+      def teardown(&procedure)
+        @context.teardown = procedure
       end
       alias_method :Teardown, :teardown
 
       # TODO: Make Before and After more generic to handle before and after
-      # units, contexts/concerns, etc.
-      
-      # Define a before procedure for this case.
-      def before(*matches, &block)
-        @testcase.before[matches] = block
+      # units, contexts/concerns, etc?
+
+      # Define a _complex_ before procedure. The #before method allows
+      # before procedures to be defined that are triggered by a match
+      # against the unit's target method name or _aspect_ description.
+      # This allows groups of tests to be defined that share special
+      # setup code.
+      #
+      # @example
+      #
+      #   unit :puts => "standard output (@stdout)" do
+      #     puts "Hello"
+      #   end
+      #
+      #   before /@stdout/ do
+      #     $stdout = StringIO.new
+      #   end
+      #
+      #   after /@stdout/ do
+      #     $stdout = STDOUT
+      #   end
+      #
+      # @param [Array<Symbol,Regexp>] matches
+      #   List of match critera that must _all_ be matched
+      #   to trigger the before procedure.
+      #
+      def before(*matches, &procedure)
+        @testcase.before[matches] = procedure
       end
       alias_method :Before, :before
 
-      # Define an after procedure for this case.
-      def after(*matches, &block)
-        @testcase.after[matches] = block
+      # Define a _complex_ after procedure. The #before method allows
+      # before procedures to be defined that are triggered by a match
+      # against the unit's target method name or _aspect_ description.
+      # This allows groups of tests to be defined that share special
+      # teardown code.
+      #
+      # @example
+      #
+      #   unit :puts => "standard output (@stdout)" do
+      #     puts "Hello"
+      #   end
+      #
+      #   before /@stdout/ do
+      #     $stdout = StringIO.new
+      #   end
+      #
+      #   after /@stdout/ do
+      #     $stdout = STDOUT
+      #   end
+      #
+      # @param [Array<Symbol,Regexp>] matches
+      #   List of match critera that must _all_ be matched
+      #   to trigger the after procedure.
+      #
+      def after(*matches, &procedure)
+        @testcase.after[matches] = procedure
       end
       alias_method :After, :after
 
-      #
-      #def prepare(&block)
-      #  @testcase.prepare = block
-      #end
-      #alias_method :Prepare, :prepare
+      # Define a "before all" procedure.
+      def prepare(&procedure)
+        before(&procedure)
+      end
+      alias_method :Prepare, :prepare
 
-      #
-      #def cleanup(&block)
-      #  @testcase.cleanup = block
-      #end
-      #alias_method :Cleanup, :cleanup
+      # Define an "after all" procedure.
+      def cleanup(&procedure)
+        after(&procedure)
+      end
+      alias_method :Cleanup, :cleanup
 
-      # Load a helper script applicable to this test case.
+      # Load a helper script applicable to this test case. Unlike requiring
+      # a helper script, the #helper method will eval the file's contents
+      # directly into the test context (using instance_eval).
+      #
+      # @param [String] file
+      #   File to eval into test context.
+      #
       def helper(file)
         instance_eval(File.read(file), file)
       end

data/notes/2010-05-05-coverage.rdoc

@@ -0,0 +1,47 @@
+= 2010-05-05 Getting Good Coverage
+
+Getting good coverage analysis is not easy. The difficulty comes
+is determining what is of interest to the tests and what
+is not. That isn't so hard with completely new code, but
+core extensions, for instance, are challenging to isolate
+from original methods.
+
+Thee issue can mostly be taken care of by taking a canonical
+snapshot of the system before loading the tests. Then taking
+a snapshot after loading the tests and comparing the two.
+For the most part the difference will be the code in need of
+coverage.
+
+Unfortunately helper code still gets in the way of taking these
+snapshots. As a result I have determined there are only four
+possible complete solutions.
+
+1) Use a Ruby lexer/parser to syntatically deconstruct the
+target libraries. This is a complex solution, and not one
+I relish trying.
+
+2) All helpers must go in special files that are preloaded so
+the snapshot can isolate it from the actual target code. This
+means any mocks, for instance, would have to be defined in
+separate files for the the test(s) that might use them. This
+solution it good in that it actually encourges the writing
+reusable helper code, but it can be annoying when writting
+one-off mocks and such.
+
+3) As an alternate to #2, Lemon could provide a method
+for specifying that a class/module or method is a helper
+and can simply be ignored when analysing coverage.
+
+4) Lastly, the library file being covered can be specified
+with a special method, e.g. #Covers. The method would act
+just like +#require+ except that it takes a snapshot before and
+after the loading the library, and in this way builds up
+a table of proper coverage targets.
+
+Options #2 and #3 have proven lack luster. It's simply too
+much overhead involved to get good coverage. Option #4 is the most
+robust choice. Unfortunately coverage reports can be very slow
+if there are lot of files to cover --Snapshots can take a second
+or two to create. Hopefully it can be sped up with refinement,
+but at the very least the coverage reporting if optional.
+

data/notes/2010-05-06-files_not_classes.rdoc

@@ -0,0 +1,19 @@
+= 2010-05-06 Files, Not Classes
+
+Just had a realization about my approch to Lemon tests.
+Until now I have equated the test-case to the class/module
+and the test-unit to the method. That makes sense, but it means
+I have left out a very important factor in the the design
+of tests: the file.
+
+I had defined a test-suite as the entire set of tests to
+be run. But I think now I am mistaken. The suite should
+correspond to the fiel being tested. Often that will mean
+one test-case per test-suite, but that's okay.
+
+After the next release, 0.7.0, I will implement this
+refactorization. I beleive it should ultimately help
+improve test coverage as well.
+
+
+

data/notes/2010-07-11-acid_testing.rdoc

@@ -0,0 +1,52 @@
+= 2010-07-11 | Kool-Aid 
+
+Taking Unit Testing to the next level with a dab of DBC.
+
+Say we have,
+
+  class K
+
+    def f1(a1)
+      g1(a1)
+    end
+
+    def g1(a1)
+      a1 + 1
+    end
+
+  end
+
+Now what do we want to say about K#f1?
+
+  unit K, :f1 do |a|
+    case a
+    when 1
+      result do |r|
+        r.assert == 2
+      end
+    end
+  end
+
+Now later we induce labor.
+
+  k = K.new
+  k.f1(1)
+
+It does't really matter what the result class contains, or how it 
+even gets called. Thus it can test side-effects as well as simple
+functional results.
+
+Okay, so how do we implement this?
+
+  class K
+
+    alias "f1:lemon", :f1
+
+    def f1(a1)
+      Lemon.verify_unit(binding) do
+        send("f1:lemon", a1)
+      end
+    end
+
+  end
+

data/notes/2010-08-02-enforcing-the-unit.md

@@ -0,0 +1,68 @@
+2010-08-02 | Enforcing the Unit
+
+The current API for creating a Lemon unit testcase looks like this:
+
+    covers 'someclass'
+
+    testcase SomeClass do
+
+      unit :some_method => "does something or another" do
+        # ...
+      end
+
+    end
+
+As it currentlt standa the current design is little more than a means of
+organization, orienting the developer to think in terms of test units.
+What is does not do is enforce the actual testing the the unit referenced.
+We could put any old mess in the unit block and as long as it did not raise
+an exception, it would get a *pass*.
+
+Taking some time to consider this in depth, I've concieved of a way in which
+that use of the method could in fact be enforced.
+
+    covers 'someclass'
+
+    testcase SomeClass do
+
+      setup do
+        SomeClass.new
+      end
+
+      unit :some_method => "does something or another" do |unit|
+        unit.object      # object from setup
+        unit.call(...)   # calls #some_method on unit.object
+      end
+
+    end
+
+What is intersting about this, beyond that fact that it enforces the use of
+the class or module and method involved, but that it also does so in
+a way naturally suited to mocking --the `unit` delegator could even have
+mocking methods built-in.
+
+      unit :some_method => "does something or another" do |unit|
+        unit.receives.foo(:bar)  # object from setup would receive this call
+        unit.returns(:baz)       # the subsequent #call will return this
+        unit.call(...)           # calls #some_method on unit.object
+      end
+
+On the downside this approach limits what can be done in the unit block.
+One _has_ to utilize the object as defined in `setup` and one _has_ to invoke
+the unit method via the `#call` interface. Though, I suppose one could argue
+that these limitations are a good thing, as they help the unit stay narrowly
+focused on that goal at hand.
+
+I think this approach is worth considering for a possible furture version.
+Perhaps a "Lemon 2.0". For the time being I believe we can enforce the unit
+without resorting this major API change.
+
+The next release of Lemon will temporarily override the unit method on the
+target class for each unit execution. If the unit method gets called within
+the unit block, then it will be noted by the overridden method before passing
+off to the original definition. The approach is perhaps a bit draconian, and 
+is certainly only possible thanks to the remarkable dynamicism of Ruby, but
+it should work perfectly well. So now, if the target method is not called within
+the taget block, the unit will raise a Pending exception, regardless of the 
+code in the block. Unit Enforced!
+

data/notes/2010-08-03-new-api.md

@@ -0,0 +1,37 @@
+# 2010-08-03 | A New API
+
+Simplified API. There is one main method.
+
+  unit_test SomeClass, :some_method, "description" do
+    # test ...
+  end
+
+It will be a global method. The block notations would still work, but
+they would simple become wrappers for the main method.
+
+  testcase SomeClass do
+
+    unit :some_method, "description" do
+
+    end
+
+  end
+
+If I can make it backward compatible, I may also allow something like:
+
+  testcase SomeClass do
+
+    unit :some_method do
+
+      concern "description" do
+
+      end
+
+    end
+
+  end
+
+By using this global method, I should be able to simplify the underlying
+implementation a great deal, which has been major concern about Lemon
+as of late.
+