lemon 0.8.1 → 0.8.2

data/HISTORY.rdoc

@@ -1,5 +1,20 @@
 = RELEASE HISTORY
 
+== 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
+improves Lemon's speed. In addition #setup and #teardown have been introduced
+for performing procedures before and after each unit test.
+
+Changes:
+
+* Overhaul coverage analysis.
+* Add TestCase#setup and #teardown methods.
+* TestCase#concern and #context are just aliases of #setup.
+* Improved output formats.
+
+
 == 0.8.1 / 2010-07-11
 
 This release adds a timer to the verbose output, which help isolate unit tests

data/README.rdoc

@@ -23,30 +23,40 @@ Say our library 'mylib.rb' consists of the class X:
 
 The simplest test case would be written as follows:
 
-  Covers 'mylib'
+  covers 'mylib'
 
-  TestCase X do
-    Unit :a => "method #a does something expected" do
+  testcase X do
+    unit :a => "method #a does something expected" do
       x = X.new
       x.a.assert.is_a? String
     end
   end
 
-The +Covers+ method works just like +require+ with the exception that loading the file does not occur until just before the tests are run. This allows Lemon to calculate accurate coverage reports.
+The +Covers+ method works just like +require+ with the exception that Lemon records the file for refernce --under certain scenarios it can be used to improve overall test covered.
 
-As tests grow, we might need to organize them into special concerns. For this Lemon provides the #Concern method.
+As tests grow, we might need to organize them into special concerns. For this Lemon provides a #concern method and a #setup method. Technically the two methods are the same, but #concern is used more for descriptive purposes whereas #setup is used to create an instance of the testcase's target class.
 
-  Covers 'mylib'
+  covers 'mylib'
 
-  TestCase X do
-    Concern "Description of a concern that the following unit tests address."
+  testcase X do
+    setup "Description of a concern that the following unit tests address." do
+      X.new
+    end
 
-    Unit :a => "method #a does something expected" do
-      x = X.new
+    unit :a => "method #a does something expected" do |x|
       x.a.assert.is_a? String
     end
   end
 
+Notice that the parameter passed to the block of +unit+ methdod is the instance of +X+ created in the +setup+ block. This block is run for every subsequent +Unit+ untill a new concern is defined.
+
+In conjunction with the #setup methods, there is a #teardown method which can be used "tidy-up" after each unit run if need be.
+
+Lastly, there are the +before+ and +after+ methods which can be used only once for each testcase. The +before+ method defines a procedure to run before any of the testcase's units are run, and the +after+ method defines a procedure to run after that are all finished.
+
+That is the bulk of the matter forf writing Lemon tests. There are few other features not mentions here. You can learn more about hose by reading the wiki[http://wiki.github.com/proutils/lemon].
+
+
 === Running Tests
 
 To run tests use the +lemon+ command-line utility.
@@ -57,26 +67,34 @@ Normal output is typical <i>dot-progress</i>. For verbose output, use the <code>
 
   $ lemon -v test/cases/name_case.rb
 
+Other output types can be specified by the `--format` or `-f` option.
+
+  $ lemon -f tap test/cases/name_case.rb
+
+
 === Checking Test Coverage
 
 Lemon can check test coverage by loading your target system and comparing it to your tests. To do this supply the <code>lemon</code> command the <code>--coverage</code> or <code>-c</code> option.
 
-  $ lemon --coverage -Ilib test/cases/
+  $ lemon -c -Ilib test/cases/*.rb
 
 === Generating Test Skeletons
 
 Because of the one to one correspondence of case-unit to class-method, Lemon can also generate test scaffolding for previously written code. To do this, use the <code>--generate</code> or <code>-g</code> option and provide the lib location, or files, of the scripts for which to generate test scaffolding, and the output location for the test scripts.
 
-  $ lemon --generate -Ilib test/cases/
+  $ lemon -g -Ilib test/cases/*.rb
 
 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.
 
+=== Test Directory
+
+There is no special directory for Lemon tests. Since they are unit tests, `test/` or `test/unit/` are good choices. Other options are `cases/` and `test/cases` since each file generally defines a single testcase. However, I recommend using interface-based names, regardless of the framework you actually use. In which case, `test/unit` is still a good choice, but also `test/api` if Lemon will be the only framework you use to test the API directly.
+
 
 == COPYRIGHT
 
-(MIT License)
+(Apache 2.0 License)
 
 Copyright (c) 2009 Thomas Sawyer
 
 See LICENSE file for details.
-

data/bin/lemon

@@ -1,3 +1,4 @@
 #!/usr/bin/env ruby
-require 'lemon/command'
-Lemon::Command.run
+require 'lemon/cli'
+Lemon::CLI.run(ARGV)
+

data/demo/case_example_fail.rb

@@ -0,0 +1,15 @@
+covers File.dirname(__FILE__) + '/fixture/example.rb'
+
+testcase Example do
+
+  unit :f => "one and one is two"do
+    Example.new.f(1,1).assert == 2
+  end
+
+  unit :f do
+    ex = Example.new
+    ex.f(1,2).assert == 4
+  end
+
+end
+

data/demo/case_example_pass.rb

@@ -0,0 +1,32 @@
+covers File.dirname(__FILE__) + '/fixture/example.rb'
+
+testcase Example do
+
+  setup "without multipler" do
+    Example.new
+  end
+
+  unit :f do |ex|
+    ex.f(1,2).assert == 3
+    ex.f(2,2).assert == 4
+  end
+
+  setup "with multipler" do
+    Example.new(2)
+  end
+
+  unit :f => "incorporate the multiplier" do |ex|
+    ex.f(1,2).assert == 4
+    ex.f(2,2).assert == 6
+  end
+
+  teardown do
+    # ...
+  end
+
+  meta :m do
+    Example.m(1,1).assert == 1
+  end
+
+end
+

data/demo/case_example_pending.rb

@@ -0,0 +1,14 @@
+covers File.dirname(__FILE__) + '/fixture/example.rb'
+
+testcase Example do
+
+  unit :f => "one and one is two"do
+    Example.new.f(1,1).assert == 2
+  end
+
+  unit :f do
+    raise Pending
+  end
+
+end
+

data/demo/case_example_untested.rb

@@ -0,0 +1,10 @@
+covers File.dirname(__FILE__) + '/fixture/example.rb'
+
+testcase Example do
+
+  unit :f do
+    # notice Example#f has not been called
+  end
+
+end
+

data/demo/fixture/example-use.rb

@@ -0,0 +1,5 @@
+require File.dirname(__FILE__) + '/example.rb'
+
+ex = Example.new
+ex.f(1,2)
+

data/demo/fixture/example.rb

@@ -0,0 +1,20 @@
+class Example
+
+  def initialize(a=1)
+    @a = a
+  end
+
+  def f(x,y)
+    @a * x + y
+  end
+
+  def q(x,y)
+    x % y
+  end
+
+  def self.m(a,b)
+    a * b
+  end
+
+end
+

data/lib/lemon.rb

@@ -1,2 +1,2 @@
-require 'lemon/runner'
-require 'lemon/coverage'
+require 'lemon/meta/data'
+require 'lemon/controller/coverage_analyzer'

data/lib/lemon/cli.rb

@@ -0,0 +1,281 @@
+module Lemon
+
+  require 'lemon/meta/data'
+  require 'optparse'
+
+  # TODO: What about a config file?
+
+  # CLI Interface handle all lemon sub-commands.
+  class CLI
+
+    COMMANDS = {
+      '-t' => 'test'    , '--test' => 'test',
+      '-c' => 'coverage', '--cov'  => 'coverage', '--coverage' => 'coverage',
+      '-g' => 'generate', '--gen'  => 'generate', '--generate' => 'generate' 
+    }
+
+    #
+    def self.run(argv=ARGV)
+      new.run(argv)
+    end
+
+    #
+    def initialize(argv=ARGV)
+      @options = {}
+    end
+
+    #
+    def options
+      @options
+    end
+
+    #
+    def run(argv)
+      cmdopt  = COMMANDS.keys.find{ |k| argv.delete(k)  }
+      command = COMMANDS[cmdopt]
+
+      if command.nil? && argv.include?('--help')
+        option_commands
+        option_parser.parse!(argv)
+      end
+
+      command ||= 'test'
+
+      #option_commands
+
+      #cmd = argv.shift
+      #cmd = COMMANDS.find{ |c| /^#{cmd}/ =~ c }
+      #option_parser.order!(argv)
+
+      begin
+        __send__("#{command}_parse", argv)
+        __send__("#{command}", argv)
+      rescue => err
+        raise err if $DEBUG
+        $stderr.puts('ERROR: ' + err.to_s)
+      end
+    end
+
+    # T E S T
+
+    # Run unit tests.
+    def test(scripts)
+      require 'lemon/controller/test_runner'
+
+      loadpath = options[:loadpath] || []
+      requires = options[:requires] || []
+
+      loadpath.each{ |path| $LOAD_PATH.unshift(path) }
+      requires.each{ |path| require(path) }
+
+      #suite  = Lemon::Test::Suite.new(files, :cover=>cover)
+      #runner = Lemon::Runner.new(suite, :format=>format, :cover=>cover, :namespaces=>namespaces)
+
+      runner = Lemon::TestRunner.new(
+        scripts, :format=>options[:format], :namespaces=>options[:namespaces]
+      )
+
+      runner.run
+    end
+
+    #
+    def test_parse(argv)
+      option_parser.banner = "Usage: lemon [-t] [options] [files ...]"
+      #option_parser.separator("Run unit tests.")
+
+      option_format
+      option_verbose
+      option_namespaces
+      option_loadpath
+      option_requires
+
+      option_parser.parse!(argv)
+    end
+
+    # C O V E R A G E
+
+    # Ouput coverage report.
+    def coverage(test_files)
+      require 'lemon/controller/coverage_analyzer'
+
+      #loadpath = options[:loadpath] || []
+      #requires = options[:requires] || []
+
+      #loadpath.each{ |path| $LOAD_PATH.unshift(path) }
+      #requires.each{ |path| require(path) }
+
+      $stderr.print "Calculating... "
+      $stderr.flush
+
+      cover = Lemon::CoverageAnalyzer.new(test_files, options)
+
+      cover.calculate  # this just helps calcs get done up front
+
+      $stderr.puts
+
+      cover.render
+    end
+
+    #
+    def coverage_parse(argv)
+      option_parser.banner = "Usage: lemon -c [options] [files ...]"
+      #option_parser.separator("Check test coverage.")
+
+      option_namespaces
+      option_private
+      option_zealous
+      option_output
+      option_format
+      option_loadpath
+      option_requires
+
+      option_parser.parse!(argv)
+    end
+
+    # G E N E R A T E
+
+    # Generate test templates.
+    def generate(test_files)
+      require 'lemon/controller/scaffold_generator'
+
+      loadpath = options[:loadpath] || []
+      requires = options[:requires] || []
+
+      loadpath.each{ |path| $LOAD_PATH.unshift(path) }
+      requires.each{ |path| require(path) }
+
+      #cover = options[:uncovered]
+      #suite = Lemon::TestSuite.new(test_files, :cover=>cover) #, :cover_all=>true)
+      generator = Lemon::ScaffoldGenerator.new(test_files, options)
+
+      #if uncovered
+      #  puts cover.generate_uncovered #(output)
+      #else
+        puts generator.generate #(output)
+      #end
+    end
+
+    #
+    def generate_parse(argv)
+      option_parser.banner = "Usage: lemon -g [options] [files ...]"
+      #option_parser.separator("Generate test scaffolding.")
+
+      option_namespaces
+      option_uncovered
+      option_all
+      option_private
+      option_loadpath
+      option_requires
+
+      option_parser.parse!(argv)
+    end
+
+    # P A R S E R  O P T I O N S
+
+    def option_commands
+      option_parser.banner = "Usage: lemon [command] [options] [files ...]"
+      option_parser.on('-t', '--test', 'run unit tests [default]') do
+        @command = :test
+      end
+      option_parser.on('-c', '--cov', '--coverage', 'provide test coverage analysis') do
+        @command = :coverage
+      end
+      option_parser.on('-g', '--gen', '--generate', 'generate unit test scaffolding') do
+        @command = :generate
+      end
+    end
+
+    def option_namespaces
+      option_parser.on('-n', '--namespace NAME', 'add a namespace to output') do |name|
+        options[:namespaces] ||= []
+        options[:namespaces] << name
+      end
+    end
+
+    #def option_framework
+    #  option_parser.on('-f', '--framework NAME', 'framework syntax to output') do |name|
+    #    options[:framework] = name.to_sym
+    #  end
+    #end
+
+    def option_format
+      option_parser.on('-f', '--format NAME', 'output format') do |name|
+        options[:format] = name
+      end
+    end
+
+    def option_verbose
+      option_parser.on('-v', '--verbose', 'shortcut for `-f verbose`') do |name|
+        options[:format] = 'verbose'
+      end
+    end
+
+    def option_uncovered
+      option_parser.on('-u', '--uncovered', 'include only uncovered units') do
+        options[:uncovered] = true
+      end
+    end
+
+    def option_all
+      option_parser.on('-a', '--all', 'include all namespaces and units') do
+        options[:all] = true
+      end
+    end
+
+    def option_private
+      option_parser.on('-p', '--private', 'include private and protected methods') do
+        options[:private] = true
+      end
+    end
+
+    def option_zealous
+      option_parser.on('-z', '--zealous', 'include undefined case methods') do
+        options[:zealous] = true
+      end
+    end
+
+    def option_output
+      option_parser.on('-o', '--output DIRECTORY', 'log directory') do |dir|
+        options[:output] = dir
+      end
+    end
+
+    def option_loadpath
+      option_parser.on("-I PATH" , 'add directory to $LOAD_PATH') do |path|
+        paths = path.split(/[:;]/)
+        options[:loadpath] ||= []
+        options[:loadpath].concat(paths)
+      end
+    end
+
+    def option_requires
+     option_parser.on("-r FILE" , 'require file(s) (before doing anything else)') do |files|
+        files = files.split(/[:;]/)
+        options[:requires] ||= []
+        options[:requires].concat(files)
+      end
+    end
+
+    def option_parser
+      @option_parser ||= (
+        OptionParser.new do |opt|
+          opt.on_tail("--debug" , 'turn on debugging mode') do
+            $DEBUG = true
+          end
+          opt.on_tail("--about" , 'display information about lemon') do
+            puts "Lemon v#{Lemon::VERSION}"
+            puts "#{Lemon::COPYRIGHT}"
+            exit
+          end
+          opt.on_tail('-h', '--help', 'display help (also try `<command> --help`)') do
+            puts opt
+            exit
+          end
+        end
+      )
+    end
+
+  end
+
+end
+