gregwebs-quicktest 0.6.2

data/README

@@ -0,0 +1,145 @@
+=begin rdoc
+
+== Summary
+Quicktest - A utility for inlining ruby unit tests with the ruby code under test
+
+== Example
+run with bin/quickspec
+
+=end rdoc
+
+  class Foo
+    def initialize
+      @bar = true
+    end
+    def quicktest
+      it "bar should be initialized to true" do
+        @bar.should == true
+      end
+    end
+
+    def self.hello arg
+      "hello" + arg
+    end
+    def self.quicktest meth
+      it "should prepend 'hello' to its argument" do
+        meth["world"].should == 'hello world' # error - no space 'helloworld'
+      end
+    end
+  end
+
+=begin rdoc
+
+Running quicktest on the source of this README file outputs the following:
+  .F
+
+  1)
+  'Foo hello should prepend 'hello' to its argument' FAILED
+  expected: "hello world",
+       got: "helloworld" (using ==)
+  ./README:22:in `quicktest'
+  /home/greg/quicktest/lib/quicktest.rb:65:in `instance_eval'
+  /home/greg/quicktest/lib/quicktest.rb:65:in `run_tests'
+
+  Finished in 0.008338 seconds
+
+  2 examples, 1 failure
+
+== Usage
+=== Install
+
+  gem install quicktest
+
+=== test code
+To test a method, place another method called 'quicktest' immediately after it
+the quicktest method has one OPTIONAL argument:
+- a method object for the method under test
+
+=== execution
+run with
+
+  spec -r quicktest file_to_test
+
+There is a convenience script so that you can just run
+
+  quickspec file_to_test
+
+== Author and License
+Copyright (c) 2008 Greg Weber, http://gregweber.info
+Licensed under the MIT license
+
+== About
+
+The typical test driven development workflow requires constant switching between the file containg the source code and the the file containg the tests. When creating code, it is much faster to be able to place tests immediately after the code you are writing.  After the code has been written, it may be a good idea to move it to another file.
+
+Quicktest is designed to support quick tests in a framework agnostic way.  Currently, only an rspec testrunner is available, but it is trivial to write one for another testing framework.
+
+Quicktest uses method tracing to know the method you are testing. By default the output of a failed test will show the object and method name.
+
+== Install
+gem install quicktest
+
+== Source
+=== browser
+http://github.com/gregwebs/quicktest/tree/master
+
+=== repository
+git clone git://github.com/gregwebs/quicktest.git
+
+== Homepage
+http://gregweber.info/projects/quicktest.html
+
+== RDoc documentation
+included with the gem
+
+== Important Notes
+- def quicktest will instantiate an object for the class you are testing, which gives a convenient referenct to self in the quicktest method.  However, it calls new() without any parameters.  If you need parameters for new(), you will have to use def self.quicktest and call new() yourself
+
+== Configuration
+- when testing module instance methods, the module is included into an anonymous class.  By default, that class inherits from Object.  To change this you must define an object that the module will be included into by defining the following in the module:
+
+  def self.quicktest_include_into; String end
+
+- you can change the testing method name from quicktest to something else using the command line option
+
+  --quicktest better_testing_name
+
+== TroubleShooting
+- quicktest methods not working properly? if the class (or one of its ancestors) is overriding method tracing then including QuickTest::Tracer will fix it, but you should also fix the class or its ancestor.
+
+== Unimportant Notes
+=== production performance
+leaving test code in with your production code is not necessarily a good idea, but you can put
+
+  remove_method :quicktest
+
+at the bottom of a class to completely remove the quicktest method
+
+=== rationals
+* tests for scripts
+Definitely very useful for one file scripts, or any type of code that does not have a well established project home where the tests will be.  You can distribute the tests with script so that anyone who wants to modify it can also modify the tests instead of assuming the original author did not write any.
+You can have a flow of development where a 'quick and dirty' script becomes well tested.  Here is a shell function that tests the file before every run.
+  function test_run () { quickspec $1 && $1 }
+* documentation
+Tests are a form of documentation.  It can be argued that it is better to have all documentation include in the source
+
+* efficient TDD and prototyping
+When writing fresh code you now have the possibility to be directly next to the code under test without having to switch back and forth between files.  When you are done writing the new code, you can easily pull all the quicktest methods out and into a spec file.
+
+
+=== Origins
+Quicktest came out of my dabbling in the D programming language, which allows you to place testing blocks inline with your source code
+  unittest{
+   ...
+  }
+
+Normally, these blocks are ignored, but if you compile with a different switch, they are linked in and ran at the beginning of your program.
+Originally, I made an exact copy of this, but among other things, it requires the placement of a line like
+  (def unittest;end) if not defined? unittest
+at the beginning of the file.  It would be nice if Ruby had a similar construct built in to the language.
+
+=== implementation
+Quicktest uses method tracing to know the method you are testing.  For the object under test, testing methods are included into it, and then the test is run.
+
+
+=end rdoc

data/bin/quickspec

@@ -0,0 +1,3 @@
+#! /usr/bin/env ruby
+puts `spec -r #{File.dirname(File.dirname(File.expand_path(__FILE__)))}/lib/quicktest #{ARGV.join ' '}`
+exit $?.exitstatus

data/lib/quicktest.rb

@@ -0,0 +1,238 @@
+# :main: README
+
+# TODO
+# allow self.quicktest after instance method, and quicktest after a class method
+# test module instance methods by setting the quicktest object to include them into
+
+module QuickTest
+
+  # create module variables
+  class << self
+    # then name of the testing method, default is :quicktest
+    attr_accessor :test_method
+
+    # don't record the fact that we add Module.method_added
+    attr_accessor :ignore_first_method_added
+
+    # set which code will be running the tests
+    attr_accessor :runner, :runner_module
+
+    # when testing module instance methods
+    # this defines the class to include a module into
+    # user sets this by defining self.quicktest_include_into in a module
+    # otherwise, a generic class is used
+    attr_accessor :include_module_into
+
+    attr_accessor :last_self
+  end
+
+  # to reuse this implementation
+  # - create a module specific to the testing system
+  # - and then add a flag at the bottom of this file to
+  #   set QuickTest.runner_module to the new module
+  # The module should
+  # - implement any methods to be publicly available in the quicktest method
+  # - contain the constants
+  #   * QuickTestIgnoreClasses
+  #   * QuickTestIncludeModules
+  #
+  # see RSpecTestRunner as an example
+  #
+  # it is possible to write a test runner without re-using this code.
+  # The test runner class to be used is set at the bottom of this file
+  # with QuickTest.runner = 
+  class TestRunner
+    class << self
+      attr_accessor :methods, :tested_self
+    end
+
+    # keep a list of all traced methods
+    self.methods = []
+    def self.add_method meth
+      self.methods.push meth
+    end
+    def self.add_singleton_method meth
+      self.methods.push meth
+    end
+
+    def initialize tested, included_module=nil
+      self.class.tested_self = tested
+
+      q = tested.method QuickTest.test_method
+      tested.extend(QuickTest.runner_module)
+      QuickTest.runner_module::QuickTestIncludeModules.each do |mod|
+        tested.extend mod
+      end
+      
+      case q.arity
+      when 0 then q.call
+      when 1 then q.call tested.method(self.class.methods[-1])
+      else raise ArgumentError, "to many arguments for #{QuickTest.test_method} method"
+      end
+
+      tested.send :__quicktest_run_tests__
+
+      # removing the quicktest method will prevent Ruby from warning about the method being redefined
+      if tested.kind_of?(Class) or tested.kind_of?(Module)
+        # TODO: errors for some cases here
+        unless included_module
+          class << tested
+            remove_method QuickTest.test_method
+          end
+        end
+      else
+        tested.class.class_eval { remove_method QuickTest.test_method }
+      end
+    end
+  end
+
+  # all public instance methods are RSpec method wrappers
+  module RSpecTestRunner
+    QuickTestIgnoreClasses = [/^Spec/]
+    QuickTestIncludeModules = [Spec::Matchers]
+    @@quicktests = Hash.new
+    @@after_block = nil
+    @@before_block = nil
+
+    def before( *args, &block ) @@before_block = [args, block] end
+    def after(  *args, &block ) @@after_block  = [args, block] end
+    def it specification, &block
+      @@quicktests[(TestRunner.methods.pop.to_s << ' ' << specification)] = block
+      TestRunner.methods.clear
+    end
+
+  private
+    def __quicktest_run_tests__ # :nodoc:
+      before_args, before_block = @@before_block
+      after_args, after_block = @@after_block
+      tests = @@quicktests
+
+      describe( TestRunner.tested_self.to_s ) do
+        before(*before_args) { before_block.call } if before_block
+        after(*after_args)   { after_block.call }  if after_block
+
+        tests.each_pair do |spec, test_block|
+          it( spec ) { test_block.call }
+        end
+      end
+      @@quicktests.clear
+      @@after_block  &&= nil
+      @@before_block &&= nil
+    end
+  end
+
+  # if the class under test (or one of its ancestors)
+  # is overriding method tracing then it must include QuickTest::Tracer
+  module Tracer
+    def self.included(into)
+      if into == Class or into == Module # default include in in Module
+        self.tracer_include into
+      else
+        self.tracer_include(class<<into;self;end)
+      end
+    end
+
+    def self.tracer_include(meta)
+      meta.module_eval do
+
+        # monkeypatch the two hook methods called on method creation
+        # so they will still be called for any method other than _quicktest_
+        alias_method :__quicktest_singleton_method_added__, :singleton_method_added
+        alias_method :__quicktest_method_added__, :method_added
+
+        # ruby tracing hook
+        def singleton_method_added traced
+          # avoid infinite recursion if module is included into a class by a user
+          return if traced == QuickTest.runner.methods.last
+
+          if QuickTest.last_self != self
+            QuickTest.last_self = self
+            QuickTest.include_module_into = Object
+          end
+
+          if traced == QuickTest.test_method
+            QuickTest.runner.new self
+
+          elsif traced == :quicktest_include_into
+            QuickTest.include_module_into = self.quicktest_include_into
+
+          else
+            QuickTest.runner.add_singleton_method traced
+            __quicktest_singleton_method_added__ traced
+          end
+        end
+
+        QuickTest.ignore_first_method_added = true
+
+        # ruby tracing hook
+        def method_added traced
+          qt = QuickTest
+          # avoid infinite recursion if module is included into a class by a user
+          return if traced == qt.runner.methods.last
+
+          if traced == QuickTest.test_method
+            begin
+              qt.runner.new( *
+                if self.class != Module
+                  [self.new]
+                else
+                  [Class.new(QuickTest.include_module_into).extend(self), self]
+                end
+              )
+            rescue ArgumentError
+              puts <<-EOS
+method:
+  #{qt.runner.methods.last}
+object initialization requires arguments, use:
+  "def self.quicktest"
+instead of:
+  "def quicktest"
+EOS
+              exit(1)
+            end
+
+          else
+            unless qt.ignore_first_method_added or
+              qt.runner_module::QuickTestIgnoreClasses.detect {|m| self.to_s =~ m}
+                qt.runner.add_method traced
+            end
+
+            qt.ignore_first_method_added = false
+            __quicktest_method_added__ traced
+          end
+        end
+      end
+    end
+  end
+end
+
+
+# configurable
+QuickTest.test_method = :quicktest
+QuickTest.runner = QuickTest::TestRunner
+QuickTest.runner_module = QuickTest::RSpecTestRunner
+QuickTest.include_module_into = Object
+
+files = []
+while(arg = ARGV.shift)
+  case arg
+  when '--rspec'
+    QuickTest.runner_module = ARGV.shift ||
+      (puts "--rspec requires an argument";exit(1))
+  when '--quicktest'
+    QuickTest.test_method = ARGV.shift.to_sym ||
+      (puts "--quicktest requires an argument";exit(1))
+  else
+    (puts "unknown argument: #{arg}";exit(1)) unless File.exist? arg
+    files.push(arg)
+  end
+end
+ARGV.concat files
+
+# trace all methods
+class Module # :nodoc:
+  include QuickTest::Tracer
+end
+
+# TODO: run pending tests at exit
+#at_exit do end

data/spec/__test.rb

@@ -0,0 +1,7 @@
+def testing
+end
+def __test
+  it "should be of class Object" do
+    self.should be_kind_of(Object)
+  end
+end

data/spec/test.rb

@@ -0,0 +1,141 @@
+# regenerate test_result.txt with
+# spec -r ../lib/quicktest test.rb >| test_result.txt
+# run tests with
+# spec -r ../lib/quicktest test.rb
+# regenerate and run
+# spec -r ../lib/quicktest test.rb >| test_result.txt || spec -r ../lib/quicktest test.rb
+
+def quicktest
+  it "should be of class Object" do
+    self.should be_kind_of(Object)
+  end
+end
+# all tests for this class should always pass
+class Tester
+  def self.meth
+    "hello"
+  end
+  def self.quicktest
+    it "should say hi" do
+      meth.should == "hello"
+      lambda{raise}.should raise_error
+    end
+  end
+  def self.hello arg
+    "hello" + arg
+  end
+  def self.quicktest m
+    it "should say hello" do
+      m[' bob'].should == "hello bob"
+    end
+  end
+  def method_missing meth
+    @foo if meth == :foo
+  end
+  def initialize
+    @foo = true
+  end
+  def quicktest
+    it "foo should be true" do
+      foo.should == true
+    end
+  end
+  def bar; @foo end
+  def quicktest meth
+    it "foo should be true" do
+      meth.call.should == true
+    end
+  end
+end
+
+# test failure text
+$r = File.readlines('test_result.txt')
+3.times {$r.shift}
+
+def quicktest
+  msg = "should show class name in output"
+  it msg do
+    $r.shift.should =~ /^'#<#{self.class}:0x[^>]+>  #{msg}' FAILED$/
+    7.times {$r.shift}
+  end
+end
+@@new_meth = :new_method_added
+eval"def #@@new_meth; end"
+
+def quicktest
+  msg = "should show name of added method"
+  it msg do
+    $r.shift.should =~ /^'#<#{self.class}:0x[^>]+> #{@@new_meth} #{msg}' FAILED$/
+    7.times {$r.shift}
+  end
+end
+
+module TestModule
+  @@klass = self
+  def self.quicktest
+    msg = "should show class name in output"
+    it msg do
+      $r.shift.should =~ /^'#{@@klass}  #{msg}' FAILED$/
+      7.times {$r.shift}
+    end
+  end
+
+  @@new_singleton_meth = 'new_singleton_method_added'
+  eval"def self.#@@new_singleton_meth;end"
+
+  def self.quicktest
+    msg = "should show class name in output"
+    it msg do
+      $r.shift.should =~ /^'#{@@klass} #@@new_singleton_meth #{msg}' FAILED$/
+      7.times {$r.shift}
+    end
+  end
+
+  define_method(:the_method) {}
+  def quicktest
+    msg = "should include the module into class Object"
+    it msg do
+      $r.shift.should =~ /^'#<Class:0x[^>]+> the_method #{msg}' FAILED$/
+      7.times {$r.shift}
+    end
+  end
+end
+
+class TestClass
+  @@klass = self
+  def self.quicktest
+    msg = "should show class name in output"
+    it msg do
+      $r.shift.should =~ /^'#{@@klass}  #{msg}' FAILED$/
+      7.times {$r.shift}
+    end
+  end
+  def quicktest
+    msg = "should show class name in output"
+    it msg do
+      $r.shift.should =~ /^'#<#{self.class}:0x[^>]+>  #{msg}' FAILED$/
+      7.times {$r.shift}
+    end
+  end
+  @@new_meth = :new_method_added
+  define_method @@new_meth do end
+
+  def quicktest
+    msg = "should show name of added method"
+    it msg do
+      $r.shift.should =~ /^'#<#{self.class}:0x[^>]+> #{@@new_meth} #{msg}' FAILED$/
+      7.times {$r.shift}
+    end
+  end
+
+  @@new_singleton_meth = 'new_singleton_method_added'
+  eval"def self.#@@new_singleton_meth;end"
+
+  def self.quicktest
+    msg = "should show class name in output"
+    it msg do
+      $r.shift.should =~ /^'#{@@klass} #@@new_singleton_meth #{msg}' FAILED$/
+      7.times {$r.shift}
+    end
+  end
+end

data/tasks/gregproject.rake

@@ -0,0 +1,65 @@
+desc "run specs"
+task :spec do
+  Dir[ 'spec/*' ].each do |file|
+    out "spec #{file}"
+  end
+end
+
+require 'rubygems'
+require 'spec/rake/spectask'
+desc "verify test coverage with RCov"
+task :rcov => 'rcov:verify'
+namespace :rcov do
+  Spec::Rake::SpecTask.new('rcov') do |t|
+    t.spec_files = ['spec/*.rb']
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec']
+  end
+
+  require 'spec/rake/verify_rcov'
+  # rcov is wrong- I am actually at 100%
+  RCov::VerifyTask.new(:verify => :rcov) do |t|
+    t.threshold = 100 # Make sure you have rcov 0.7 or higher!
+    t.index_html = $rcov_index_html
+  end
+end
+
+desc "create a new gem release"
+task :release => [:test,:record,:rdoc,:website,:gem_specification,:package] do
+  Dir.chdir('pkg') do
+    release = Dir['*.gem'].sort_by {|file| File.mtime(file)}.last
+    release =~ /^[^-]+-([.0-9]+).gem$/
+    out "rubyforge login && rubyforge add_release #{$project} #{$project} #$1 #{release}"
+  end
+end
+
+desc "update website"
+file :website => ['README','Rakefile'] do
+  Dir.chdir '/home/greg/sites/projects/' do
+    out 'rake --silent projects:update'
+    out 'rake --silent deploy:rsync'
+  end
+end
+  
+require 'rake/rdoctask'
+
+Rake::RDocTask.new do |rd|  
+   rd.main = "README"  
+   rd.rdoc_dir = "doc"
+   rd.rdoc_files.include("README", "lib/**/*.rb")  
+   rd.title = "#$project rdoc"  
+   rd.options << '-S' # inline source  
+   rd.template = `allison --path`.chomp + '.rb'  
+ end
+
+desc 'git add and push'
+task :record do
+  unless `git status`.split($/).last =~ /nothing added/
+    puts `git diff`
+    ARGV.clear
+    puts "enter commit message"
+    out "git commit -a -m '#{Kernel.gets}'"
+    puts "committed! now pushing.. "
+    out 'git push origin master'
+  end
+end

data/tasks/helpers.rb

@@ -0,0 +1,36 @@
+def exit_msg(msg, code=1)
+  puts msg
+  exit(code)
+end
+def run command
+  res = `#{command}`
+  if $?.exitstatus != 0
+    exit_msg(
+      "\nfailure on command:\n  #{command.chomp}\nresult:\n  #{res}\n",
+      $?.exitstatus
+    )
+  end
+  res
+end
+def out command
+  (puts (run command))
+end
+
+def cd_tmp
+  Dir.mkdir 'tmp' unless File.directory? 'tmp'
+  Dir.chdir('tmp') do |dir|
+    yield dir
+  end
+  rm_rf 'tmp'
+end
+
+class IO
+  def self.write( file, str )
+    self.open( file, 'w' ) { |fh| fh.print str }
+  end
+  def self.read_write( file, write_file=file )
+    self.write(write_file, (yield( self.read( file ))))
+  end
+end
+
+Dir.glob('tasks/*.rake').sort.each {|fn| import fn}

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: gregwebs-quicktest
+version: !ruby/object:Gem::Version 
+  version: 0.6.2
+platform: ruby
+authors: 
+- Greg Weber
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-06 00:00:00 -08:00
+default_executable: quickspec
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+    version: 
+description: 
+email: 
+executables: 
+- quickspec
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- ./bin
+- ./doc
+- ./lib
+- ./TODO
+- ./spec
+- ./quicktest.gemspec.rb
+- ./Rakefile
+- ./tasks
+- ./README
+- ./quicktest-0.6.1.gem
+- bin/quickspec
+- doc/files
+- doc/index.html
+- doc/rdoc-style.css
+- doc/fr_method_index.html
+- doc/fr_class_index.html
+- doc/fr_file_index.html
+- doc/created.rid
+- doc/classes
+- lib/quicktest.rb
+- spec/__test.rb
+- spec/test.rb
+- tasks/helpers.rb
+- tasks/gregproject.rake
+- README
+has_rdoc: true
+homepage: http://gregweber.info/projects/quicktest.html
+post_install_message: |+
+  
+  spec and quickspec are ruby executable scripts, whose directory location must be in your PATH environment variable (or you must invoke the with the full file path).
+  
+  run tests with
+     quickspec [file1 file2 ...]
+  
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: quicktest
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: utility for inlining tests with the code tested
+test_files: []
+