lemon 0.9.0 → 0.9.1

data/.ruby

@@ -1,15 +1,16 @@
 ---
+source:
+- meta
+- VERSION
 authors:
 - name: Thomas Sawyer
   email: transfire@gmail.com
 copyrights:
-- holder: Thomas Sawyer
+- holder: Rubyworks
   year: '2009'
   license: BSD-2-Clause
-replacements: []
-conflicts: []
 requirements:
-- name: test
+- name: rubytest
 - name: ae
 - name: ansi
   version: 1.3+
@@ -25,25 +26,33 @@ requirements:
   groups:
   - test
   development: true
+- name: ripper
+  optional: true
+  engines:
+  - name: ruby
+    version: 1.8~
 dependencies: []
+alternatives: []
+conflicts: []
 repositories:
 - uri: git://github.com/proutils/lemon.git
   scm: git
-  name: origin
+  name: upstream
 resources:
   home: http://rubyworks.github.com/lemon
   code: http://github.com/rubyworks/lemon
+  bugs: http://github.com/rubyworks/lemon/issues
+extra: {}
 load_path:
 - lib
-extra:
-  manifest: MANIFEST
-alternatives: []
 revision: 0
+created: '2009-10-25'
+summary: Pucker-strength Unit Testing
 title: Lemon
-summary: Pucker-tight Unit Testing
-description: Lemon is a unit testing framework that tightly correlates class to test
-  case and method to test unit.
-organization: RubyWorks
-version: 0.9.0
 name: lemon
-date: '2011-08-11'
+description: ! 'Lemon is a unit testing framework that tightly correlates
+
+  class to test case and method to test unit.'
+organization: rubyworks
+version: 0.9.1
+date: '2012-03-09'

data/.yardopts

@@ -0,0 +1,6 @@
+--output-dir doc
+--private
+--protected
+lib/
+-
+[A-Z][A-Z]*.*

data/Config.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+profile :coverage do
+
+  config :qed do
+    require 'simplecov'
+    SimpleCov.start do
+      coverage_dir 'log/coverage'
+      #add_group "Label", "lib/qed/directory"
+    end
+  end
+
+end
+

data/{HISTORY.rdoc → HISTORY.md}

@@ -1,6 +1,21 @@
-= RELEASE HISTORY
+# RELEASE HISTORY
 
-== 0.9.0 / 2011-08-11
+## 0.9.1 / 2012-03-17
+
+Thie release fixes some evaluation scope issues, improves how omit and skip
+methods work, makes test generation usable and generally cleans-up internals.
+All in all, this release should be a fair bit more robust than previous releases
+and ready for the big 1.0 after one more good coding session.
+
+Changes:
+
+* Fix test scope so it's properly isolated.
+* Improve skip and omit methods w/ non-block forms.
+* Use Ripper instead of RubyParse for scaffolding.
+* Greatly improve usability of code generation tool.
+
+
+## 0.9.0 / 2011-08-11
 
 Version 0.9 is a huge release for Lemon. This release finally makes the transition
 to the new unit subcase syntax --a bit more verbose than the old style but a more
@@ -31,7 +46,7 @@ Changes:
 * Implemented new unit block syntax.
 
 
-== 0.8.5 / 2011-07-15
+## 0.8.5 / 2011-07-15
 
 This release fixes exit code status, which should be -1 if there
 are errors or failures.
@@ -41,7 +56,7 @@ Changes:
 * Fix exit code status.
 
 
-== 0.8.4 / 2011-07-11
+## 0.8.4 / 2011-07-11
 
 Fix reported issue #6 to get lemon passing it own tests. (Note: the
 tests need to be run with `test/fixtures` in the loadpath). There was 
@@ -57,7 +72,7 @@ Changes:
 * Lemon can test itself (albeit test are not complete).
 
 
-== 0.8.3 / 2011-05-19
+## 0.8.3 / 2011-05-19
 
 Looks like Lemon is pretty damn near 1.0 status. She probably won't get
 any major changes for a good while. This release simply adds TAP-Y/J reporters.
@@ -69,7 +84,7 @@ Changes:
 * Configuration directory can be `.lemon/`.
 
 
-== 0.8.2 / 2010-09-05
+## 0.8.2 / 2010-09-05
 
 This release overhauls how coverage is performed so it does not need to
 take a system snapshot after requiring each covered file. This greatly
@@ -84,7 +99,7 @@ Changes:
 * Improved output formats.
 
 
-== 0.8.1 / 2010-07-11
+## 0.8.1 / 2010-07-11
 
 This release adds a timer to the verbose output, which help isolate unit tests
 that are slow. It also fixed bug in Before and After advice that prevented them
@@ -95,7 +110,7 @@ Changes:
 * Add times to verbose reporter.
 
 
-== 0.8.0 / 2010-06-21
+## 0.8.0 / 2010-06-21
 
 This release removes coverage information from testing. Coverage can be time
 consuming, but running test should be as fast as possbile. For this reason 
@@ -108,7 +123,7 @@ Changes:
 * Test generator defaults to public methods only.
 
 
-== 0.7.0 / 2010-05-04
+## 0.7.0 / 2010-05-04
 
 This release fixes issue with coverage reports. To do this we have interoduced
 the +Covers+ method. This allows Lemon to distingush between code that is
@@ -125,7 +140,7 @@ Changes:
 * New Snapshot class improves encapsulation to coverage state.
 
 
-== 0.6.0 / 2010-03-06
+## 0.6.0 / 2010-03-06
 
 This release adds coverage reporting to testing and improves the generator.
 
@@ -136,7 +151,7 @@ Changes:
 * Suite class has Coverage instance.
 
 
-== 0.5.0 / 2009-12-31
+## 0.5.0 / 2009-12-31
 
 This is the initial public release of Lemon. Lemon is still under development
 and should be considered betaware, but it's API is stable and the system usable

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Lemon - Pucker-Strength Unit Testing  
+
+Copyright (c) 2009 Rubyworks. All rights reserved
+
+Licensed (spdx) BSD-2-Clause
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+(http://rubyworks.github.com/lemon)

data/README.md

@@ -10,15 +10,15 @@
 
 Lemon is a Unit Testing Framework that enforces a strict test structure mirroring the class/module and method structure of the target code. Arguably this promotes the proper technique for low-level unit testing and helps ensure good test coverage.
 
-The difference between unit testing and functional testing, and all other forms of testing for that matter, is simply a matter of where the testing *concern* lies. The concerns of unit testing are the concerns of unit tests --the individual methods.
+The difference between unit testing and functional testing, and all other forms of testing for that matter, is simply a matter of where the testing *concern* lies. The concerns of unit testing are the concerns of unit tests, which, in object-oriented design, drills down to individual methods.
 
-IMPORTANT! As of v0.9+ the API has changed. The `unit :name => "description"` notation is no longer supported.
+**IMPORTANT!** As of v0.9+ the API has changed. The `unit :name => "description"` notation is no longer supported.
 
 
 ## EXAMPLE
 
 Lemon tests are broken down into target class or module and target methods.
-Withn these lie the acutal tests.
+Within these lie the actual tests.
 
 Let's say we have a script 'mylib.rb' consisting of the class X:
 
@@ -31,20 +31,20 @@ end
 An test case for the class would be written:
 
 ``` ruby
-Covers 'mylib'
+covers 'mylib'
 
-TestCase X do
+testcase X do
 
-  Setup "Description of setup." do
+  setup "Description of setup." do
     @x = X.new
   end
 
-  Unit :a do
-    Test "method #a does something expected" do
+  method :a do
+    test "method #a does something expected" do
       @x.a.assert.is_a? String
     end
 
-    Test "method #a does something else expected" do
+    test "method #a does something else expected" do
       @x.a.assert == "x"
     end
   end
@@ -56,46 +56,60 @@ The `covers` method works just like `require` with the exception that it records
 
 The setup (also called the *concern*) is run for every subsequent test until a new setup is defined.
 
-In conjunction with the `#setup` method, there is a `#teardown` method which can be used "tidy-up" after each test if need be.
+In conjunction with the `#setup` method, there is a `#teardown` method which can be used "tidy-up" after each test.
 
-You might have also notice by the documentation that the test methods do not have to be capitalized.
+The `#unit` method is also aliased as `#methed` which is actually a bit more readable. Along with that there is `class_unit` and it's alias `class_method` for testing class-level methods. Also note that the test methods may be capitalized (e.g. `#TestCase'), if you prefer that style.
 
-That is the bulk of the matter for writing Lemon tests. To learn about additonal features not mentioned here, check-out the [User Guide](http://wiki.github.com/rubyworks/lemon).
+That is the bulk of the matter for writing Lemon tests. To learn about additional features not mentioned here, check-out the [User Guide](http://wiki.github.com/rubyworks/lemon).
 
 
 ## USAGE
 
 ### Running Tests
 
-Tests can be run using the `lemonade` command line tool.
+Tests can be run using the `lemons` command line tool.
 
-    $ lemonade test test/cases/name_case.rb
+    $ lemons test test/cases/name_case.rb
 
-Lemon utilizes the Ruby Test system to run tests, the `lemonade test` command simply passes off the running of tests to `ruby-test`. So the `ruby-test` command-line utility can also be used directly:
+Lemon utilizes the RubyTest universal test harness to run tests, the `lemons test` command simply passes off control to `rubytest` command. So the `rubytest` command-line utility can also be used directly:
 
-    $ ruby-test -r lemon test/cases/name_case.rb
+    $ rubytest -r lemon test/cases/name_case.rb
 
-Normal output is typical _dot-progress_. Other output types can be specified by the `--format` or `-f` option.
+Normal output is typically a _dot progression_. Other output types can be specified by the `--format` or `-f` option.
 
-    $ ruby-test -r lemon -f tap test/cases/name_case.rb
+    $ rubytest -r lemon -f tapy test/cases/name_case.rb
 
-See [Ruby Test](http://rubyworks.github.com/test) for more information.
+See [RubyTest](http://rubyworks.github.com/rubytest) for more information.
 
 ### Checking Test Coverage
 
-Lemon can check test coverage by loading your target system and comparing it to your tests. To do this use the <code>lemonade coverage</code> command the utility.
+Lemon can check per-unit test coverage by loading your target system and comparing it to your tests. To do this use the `lemons coverage` command.
 
-    $ lemonade coverage -Ilib test/cases/*.rb
+    $ lemons coverage -Ilib test/cases/*.rb
 
-The coverage tool provides class/module and method coverage and is meant to as a "guidance system" for developers working toward complete test coverage. It is not an lines-of-code coverage tool and should not be considered a substitute for one.
+The coverage tool provides class/module and method coverage and is meant as a "guidance system" for developers working toward complete test coverage. It is not a LOC (lines of code) coverage tool and should not be considered a substitute for one.
 
 ### Generating Test Skeletons
 
-Because of the one to one correspondence of test case and unit test to class/module and method, Lemon can also generate test scaffolding for previously written code. To do this, use the <code>lemonade generate</code> command line utility and provide the lib location or files of the scripts for which to generate test scaffolding, and the output location for the test scripts.
+Because of the one-to-one correspondence of test case and unit test to class/module and method, Lemon can also generate test scaffolding for previously written code. To do this, use the `lemons generate` or `lemons scaffold` command line utilities. 
 
-    $ lemonade generate -Ilib test/cases/*.rb
+The `generate` command outputs test skeletons to the console. You can use this output as a simple reference or redirect the output to a file and then copy and paste portions into separate files as desired. The `scaffold` command will create actual files in your test directory. Other than that, and the options that go with it (e.g. `--output`), the two commands are the same.
 
-Generating test case scaffolding from code will undoubtedly strike test-driven developers as a case of putting the cart before the horse. However, it is not unreasonable to argue that high-level, behavior-driven, functional testing frameworks, such as Q.E.D. and Cucumber are better suited to test-first methodologies. While test-driven development can obviously be done with Lemon, unit-testing is more appropriate for testing specific, critical portions of code, or for achieving full test coverage for mission critical applications.
+To get a set of test skeletons simply provide the files to be covered.
+
+    $ lemons generate lib/**/*.rb
+
+The generator can take into account tests already written, so as not to include units that already have tests. To do this provide a list of test files after a dash (`-`).
+
+    $ lemons generate -Ilib lib/**/*.rb - test/**/*.rb
+
+Test skeletons can be generated on a per-file or per-case bases. By case is the default. Use the `-f`/`--file` option to do otherwise.
+
+    $ lemon scaffold -f lib/foo.rb
+
+The default output location is `test/`. You can change this with the `-o/--output` option.
+
+Generating test case scaffolding from code will undoubtedly strike test-driven developers as a case of putting the cart before the horse. However, it is not unreasonable to argue that high-level, behavior-driven, functional testing frameworks, such as Q.E.D. and Cucumber, are better suited to test-first methodologies. While test-driven development can obviously be done with Lemon, unit-testing best suited to testing specific, critical portions of code, or for achieving full test coverage for mission critical applications.
 
 ### Test Directory
 
@@ -106,8 +120,8 @@ There is no special directory for Lemon tests. Since they are unit tests, `test/
 
 Lemon Unit Testing Framework
 
-Copyright (c) 2009 Thomas Sawyer 
+Copyright (c) 2009 Thomas Sawyer, Rubyworks
 
-Lemon is distributed according to the terms of the **FreeBSD** License.
+Lemon is distributable in accordance with the **FreeBSD** license.
 
-See the COPYING.rdoc file for details.
+See the LICENSE.txt for details.

data/SPECSHEET.md

@@ -0,0 +1,314 @@
+== Complete Coverage
+
+=== Complete Coverage of Public Interface
+
+Given an example script in 'lib/complete_example.rb' as follows:
+
+    class C1
+      def f1; "f1"; end
+      def f2; "f2"; end
+      def f3; "f3"; end
+    end
+
+    class C2
+      def g1; "g1"; end
+      protected
+      def g2; "g2"; end
+      private
+      def g3; "g3"; end
+    end
+
+And given a test case in 'test/complete_example_case.rb' as follows:
+
+    Covers 'complete_example.rb'
+
+    TestCase C1 do
+      method :f1 do 
+        test "Returns a String"
+      end
+      method :f2 do
+        test "Returns a String"
+      end
+      method :f3 do
+        test "Returns a String"
+      end
+    end
+
+    TestCase C2 do
+      method :g1 do
+        test "Returns a String"
+      end
+    end
+
+And we get the coverage information via CoverageAnalyer.
+
+    require 'lemon'
+
+    tests = ['test/complete_example_case.rb']
+
+    coverage = Lemon::CoverageAnalyzer.new(tests, :loadpath=>'lib')
+
+Then we should see that there are no uncovered units.
+
+    coverage.uncovered_units.assert == []
+
+And there should be 4 covered units,
+
+    coverage.covered_units.size.assert == 4
+
+one for each public class and method.
+
+    units = coverage.covered_units.map{ |u| u.to_s }
+
+    units.assert.include?('C1#f1')
+    units.assert.include?('C1#f2')
+    units.assert.include?('C1#f3')
+
+    units.assert.include?('C2#g1')
+
+There should not be any coverage for private and protected methods.
+
+    units.refute.include?('C2#g2')
+    units.refute.include?('C2#g3')
+
+In addition there should be no uncovered_cases or undefined_units.
+
+    coverage.undefined_units.assert = []
+    coverage.uncovered_cases.assert = []
+
+=== Including Private and Protected Methods
+
+We will use the same example classes as above, but in this case we will
+add coverage for private and protected methods as well, given a test case
+in 'test/complete_example_case.rb' as follows:
+
+    Covers 'complete_example.rb'
+
+    TestCase C1 do
+      method :f1 do
+        test "Returns a String"
+      end
+      method :f2 do
+        test "Returns a String"
+      end
+      method :f3 do
+        test "Returns a String"
+      end
+    end
+
+    TestCase C2 do
+      method :g1 do
+        test "Returns a String"
+      end
+      method :g2 do
+        test "Returns a String"
+      end
+      method :g3 do
+        test "Returns a String"
+      end
+    end
+
+And we get the coverage information via CoverageAnalyer.
+
+    require 'lemon'
+
+    tests = ['test/complete_example_case.rb']
+
+    coverage = Lemon::CoverageAnalyzer.new(tests, :loadpath=>'lib', :private=>true)
+
+Notice the use of the +private+ option. This will add private and protected
+methods to the coverage analysis.
+
+Then we should see that there are no uncovered units.
+
+    coverage.uncovered_units.assert == []
+
+And there should be 6 covered units,
+
+    coverage.covered_units.size.assert == 6
+
+one for each class and method.
+
+    units = coverage.covered_units.map{ |u| u.to_s }
+
+    units.assert.include?('C1#f1')
+    units.assert.include?('C1#f2')
+    units.assert.include?('C1#f3')
+
+    units.assert.include?('C2#g1')
+    units.assert.include?('C2#g2')
+    units.assert.include?('C2#g3')
+
+In addition there should be no uncovered cases or undefined units.
+
+    coverage.undefined_units.assert = []
+    coverage.uncovered_cases.assert = []
+
+
+== Incomplete Coverage
+
+=== Incomplete Coverage of Public Interface
+
+Given an example script in 'lib/incomplete_example.rb' as follows:
+
+    class I1
+      def f1; "f1"; end
+      def f2; "f2"; end
+      def f3; "f3"; end
+    end
+
+    class I2
+      def g1; "g1"; end
+      protected
+      def g2; "g2"; end
+      private
+      def g3; "g3"; end
+    end
+
+    class I3
+      def h1; "h1"; end
+    end
+
+And given a test case in 'test/incomplete_example_case.rb' as follows:
+
+    Covers 'incomplete_example.rb'
+
+    TestCase I1 do
+      method :f1 do
+        test "Returns a String"
+      end
+      method :f2 do
+        test "Returns a String"
+      end
+    end
+
+    TestCase I2 do
+      method :x1 do
+        test "Does not exist"
+      end
+    end
+
+And we get the coverage information via CoverageAnalyer.
+
+    require 'lemon'
+
+    tests = ['test/incomplete_example_case.rb']
+
+    coverage = Lemon::CoverageAnalyzer.new(tests, :loadpath=>'lib')
+
+Then we should see that there are 2 unconvered units, I1#f3 and I2#g1
+because no testcase unit was defined for them and they are both public methods.
+
+    units = coverage.uncovered_units.map{ |u| u.to_s }
+
+    units.assert.include?('I1#f3')
+    units.assert.include?('I2#g1')
+
+    units.size.assert == 2
+
+You might expect that 'I3#h1' would be in the uncovered units list as well,
+since it is a public method and no test unit covers it. However, there is
+no test case for I3 at all, so Lemon takes that to mean that I3 is of
+no interest.
+
+    units.refute.include?('I3#h1')
+
+But I3 will be listed in the uncovered cases list.
+
+    coverage.uncovered_cases == [I3]
+
+Note that uncovered case methods can be included in the uncovered units list
+by setting the +zealous+ option, which we will demonstrated later.
+
+There should still be 3 covered units, I1#f1, I1#f2 and I2#x1.
+
+    coverage.covered_units.size.assert == 3
+
+    units = coverage.covered_units.map{ |u| u.to_s }
+
+    units.assert.include?('I1#f1')
+    units.assert.include?('I1#f2')
+    units.assert.include?('I2#x1')
+
+But we will not find any covered units for class I2.
+
+    units.refute.include?('I2#g1')
+    units.refute.include?('I2#g2')
+    units.refute.include?('I2#g3')
+
+Notice also that we defined a unit for I2#x1, a method that does not exist.
+So it should be listed in the undefined units list.
+
+    coverage.undefined_units.size.assert == 1
+
+    units = coverage.undefined_units.map{ |u| u.to_s }
+
+    units.assert.include?('I2#x1')
+
+
+== Core Extension Coverage
+
+=== Kernel Extensions
+
+Given an example script in 'lib/extensions_example.rb' as follows:
+
+    module Kernel
+      def f1; "f1"; end
+      def f2; "f2"; end
+      def f3; "f3"; end
+    end
+
+And given a test case in 'test/extensions_example_case.rb' as follows:
+
+    Covers 'extensions_example.rb'
+
+    TestCase Kernel do
+      method :f1 do
+        test do
+          fl.assert == "f1"
+        end
+      end
+      method :f2 do
+        test do
+          f2.assert == "f2"
+        end
+      end
+    end
+
+And we get the coverage information via CoverageAnalyer.
+
+    require 'lemon'
+
+    tests = ['test/extensions_example_case.rb']
+
+    coverage = Lemon::CoverageAnalyzer.new(tests, :loadpath=>'lib')
+
+Then we should see that there are two covered units, #f1 and #f2.
+
+    coverage.covered_units.size.assert == 2
+
+    units = coverage.covered_units.map{ |u| u.to_s }
+
+    units.assert.include?('Kernel#f1')
+    units.assert.include?('Kernel#f2')
+
+    units.refute.include?('Kernel#f3')
+
+And we should see one unconvered unit, #f3.
+
+    coverage.uncovered_units.size.assert == 1
+
+    units = coverage.uncovered_units.map{ |u| u.to_s }
+
+    units.assert.include?('Kernel#f3')
+
+There should be zero uncovered cases.
+
+    coverage.uncovered_cases == []
+
+And zero undefined unit.
+
+    coverage.undefined_units == []
+
+
+