rubytest 0.3.0

data/.ruby

@@ -0,0 +1,45 @@
+---
+source:
+- var
+authors:
+- name: trans
+  email: transfire@gmail.com
+copyrights:
+- holder: RubyWorks
+  year: '2011'
+  license: BSD-2-Clause
+replacements: []
+alternatives: []
+requirements:
+- name: ansi
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: qed
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git@github.com:rubyworks/ruby-test.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/ruby-test
+  code: http://github.com/rubyworks/ruby-test
+  mail: http://groups.google.com/group/rubyworks-mailinglist
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2011-07-23'
+summary: Ruby Universal Test Harness
+title: Ruby Test
+version: 0.3.0
+name: rubytest
+description: ! "Ruby Test is a universal test harness for Ruby. It can handle any
+  compliant \ntest framework, even running tests from multiple frameworks in a single
+  pass."
+date: '2011-12-23'

data/.test

@@ -0,0 +1,11 @@
+Test.run(:default) do |run|
+  run.files << 'test/*_case.rb'
+end
+
+Test.run(:cov) do |run|
+  run.files << 'test/*_case.rb'
+  SimpleCov.start do |cov|
+    cov.coverage_dir = 'log/coverage'
+  end
+end
+

data/HISTORY.md

@@ -0,0 +1,43 @@
+# RELEASE HISTORY
+
+## 0.3.0 / 2011-12-22
+
+Technically this is a fairly minor release that improves backtrace output
+and prepares the `LOAD_PATH` automtically if a `.ruby` file is present.
+However, it is significant in that the name of the gem has been changed
+from `test` to `rubytest`.
+
+Changes:
+
+* Change gem name to `rubytest`.
+* Improve backtrace filtering in reporters.
+* Setup `LOAD_PATH` based on .ruby file if present.
+
+
+## 0.2.0 / 2011-08-10
+
+With this release Ruby Test is essentially feature complete. Of course there
+are plenty of tweaks and improvements yet to come, but Ruby Test is fully usable
+at this point. Only one major aspect of the design remains in question --the
+way per-testcase "before and after all" advice is handled. Other than that
+the API fairly solid, even as this early state of development. Always helps
+when you have a spec to go by!
+
+Changes:
+
+* Use Config class to look-up .test file.
+* Support hard testing, topic and pre-case setup.
+* Add autorun.rb runner script.
+* Add a test reporter to use for testing Ruby Test itself.
+* Improved dotprogess reporter's handling of omissions.
+* Add unit selection to test runner.
+
+
+## 0.1.0 / 2011-07-30
+
+First release of Ruby Test.
+
+Changes:
+
+* It's Your Birthday!
+

data/NOTICE.md

@@ -0,0 +1,33 @@
+# COPYRIGHT NOTICES
+
+## Ruby Test
+
+**Project**   | Ruby Test
+--------------|------------------------------------------
+**Website**   | http://rubyworks.github.com/ruby-test
+**License**   | BSD-2-Clause
+**Copyright** | (c) 2011 Rubyworks
+
+    Copyright 2011 Rubyworks. All rights reserved.  
+
+    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.
+

data/README.md

@@ -0,0 +1,112 @@
+# Ruby Test
+
+[Homepage](http://rubyworks.github.com/rubytest) /
+[User Guide](http://wiki.github.com/rubyworks/rubytest) /
+[Development](http://github.com/rubyworks/rubytest) /
+[Issues](http://github.com/rubyworks/rubytest/issues)
+
+## Description
+
+Ruby Test is a universal test harness for Ruby that can be used by any Ruby
+test framework. Ruby Test defines a simple specification for compliance, which
+allows tests from various frameworks to all run 
+
+Ruby Test defines a straight-forward specification that any test framework can 
+easily support which allows Ruby Test to run the frameworks tests through a
+single uniform user interface in a single pass.
+
+## Specification
+
+The universal access point for testing is the `$TEST_SUITE` global array. A test
+framework need only add compliant test objects to `$TEST_SUITE`. 
+Ruby Test will iterate through these objects. If a test object responds to
+`#call`, it is run as a test procedure. If it responds to `#each` it is iterated
+over as a test case with each entry handled in the same manner. All test 
+objects must respond to `#to_s` so their description can be used in test
+reports.
+
+Any raised exception that responds to `#assertion?` in the affirmative is taken
+to be a failed assertion rather than simply an error. Ruby Test extends the
+Exception class to support this method for all exceptions.
+
+A test framework may raise a `NotImplementedError` to have a test recorded
+as "pending" --a _todo_ item to remind the developer of tests that still
+need to be written. The `NotImplementedError` is a standard Ruby exception
+and a subclass of `ScriptError`.
+
+If the `NotImplmentedError` responds in the affirmative to `#assertion?` then
+the test is taken to be a purposeful _omission_, rather than simply pending.
+
+That is the crux of Ruby Test specification. Ruby Test supports some
+additional features that can makes its usage even more convenient.
+See the [Wiki](http://github.com/rubyworks/test/wiki) for further details.
+
+
+## Usage
+
+There are a few ways to run tests. First, there is a command line tool:
+
+    $ rubytest
+
+The command line tool takes various options, use `--help` to see them.
+Be sure to load in your test framework or framework's Ruby Test adapter.
+
+Preconfigurations can be defined in a `.test` file, e.g.
+
+    Test.run 'default' do |r|
+      r.format = 'progress'
+      r.requires << 'lemon'
+      r.files << 'test/*_case.rb'
+    end
+
+There is also a 'rubytest/autorun.rb' library script that can be loaded which
+creates an `at_exit` runner, for which `test.rb` provides a nice shortcut:
+
+    $ ruby -r test
+
+There is also a Rake task.
+
+    require 'rubytest/rake'
+
+    Test::Rake::TestTask.new
+
+A Detroit plugin is in the works and should be available soon.
+
+
+## Installation
+
+Ruby Test is available as Gem package.
+
+    $ gem install rubytest
+
+
+## Requirements
+
+Ruby Test uses the [ANSI](http://rubyworks.github.com/ansi) gem for color output.
+
+Because of the "foundational" nature of this library we will look at removing
+this dependencies for future versions, but for early development the 
+requirements does the job and does it well.
+
+
+## Development
+
+Ruby Test is still a "nuby" gem. Please feel OBLIGATED to help improve it ;-)
+
+Ruby Test is a [RubyWorks](http://rubyworks.github.com) project. If you can't
+contribue code, you can still help out by contributing to our development fund.
+
+
+## Reference Material
+
+[1] [Standard Definition Of Unit Test](http://c2.com/cgi/wiki?StandardDefinitionOfUnitTest)
+
+
+## Copyrights
+
+Copyright (c) 2011 Rubyworks
+
+Made available according to the terms of the <b>FreeBSD license</b>.
+
+See NOTICE.md for details.
+

data/bin/rubytest

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'rubytest'
+Test::Runner.cli(*ARGV)
+

data/demo/01_test.md

@@ -0,0 +1,29 @@
+## Defining a Test
+
+Any object in a test suite that responds to #call, will be executed as
+a test. For instance, given an abtriray object defined as follows.
+
+    test = Object.new
+
+    def test.okay
+      @okay
+    end
+
+    def test.call
+      @okay = true
+    end
+
+If we pass this to a test runner as part of a test suite,
+
+    runner = Test::Runner.new(:suite=>[test], :format=>'test')
+
+    success = runner.run
+
+We will see that the test was called.
+
+    test.assert.okay
+
+And testing was successful.
+
+    success.assert == true
+

data/demo/02_case.md

@@ -0,0 +1,34 @@
+## Defining a Test Case
+
+Any object in a test suite that responds to #each, will be iterated over
+and each entry run a test or another sub-case. For instance, given an abitrary
+object defined as follows.
+
+    test = Object.new
+
+    def test.okay
+      @okay
+    end
+
+    def test.call
+      @okay = true
+    end
+
+And placed into an array.
+
+    tests = [test]
+
+If we pass this to a test runner as part of a test suite,
+
+    runner = Test::Runner.new(:suite=>[tests], :format=>'test')
+
+    success = runner.run
+
+We will see that the test was called.
+
+    test.assert.okay
+
+And testing was successful.
+
+    success.assert == true
+

data/demo/applique/ruby-test.rb

@@ -0,0 +1,2 @@
+require 'test/runner'
+

data/lib/rubytest/autorun.rb

@@ -0,0 +1,19 @@
+#$TEST_SUITE = [] unless defined?($TEST_SUITE)
+
+if RUBY_VERSION < '1.9'
+  require 'ruth'
+else
+  require_relative '../ruth'
+end
+
+at_exit {
+  suite   = $TEST_SUITE
+  options = {
+    :format => ENV['rubytest-format']  # TODO: better name?
+  }
+
+  runner  = Ruth::Test::Runner.new(suite, options)
+  success = runner.run
+  exit -1 unless success
+}
+

data/lib/rubytest/cli.rb

@@ -0,0 +1,106 @@
+module Test
+
+  # Command line interface.
+  class Runner
+
+    # Test runner command line interface.
+    #
+    def self.cli(*argv)
+      runner = Runner.new
+
+      Test::Config.load
+
+      cli_options(runner, argv)
+
+      Test::Config.load_path_setup  #unless runner.autopath == false
+
+      begin
+        success = runner.run
+        exit -1 unless success
+      rescue => error
+        raise error if $DEBUG
+        $stderr.puts('ERROR: ' + error.to_s)
+      end
+    end
+
+    #
+    def self.cli_options(runner, argv)
+      require 'optparse'
+
+      config = Test.config.dup
+      config_loaded = false
+
+      common  = config.delete('common')
+      default = config.delete('default')
+
+      common.call(runner) if common
+
+      OptionParser.new do |opt|
+        opt.banner = "Usage: #{$0} [options] [files ...]"
+
+        unless config.empty?
+          opt.separator "PRESET OPTIONS:"
+          config.each do |name, block|
+            opt.on("--#{name}") do
+              block.call(runner)
+            end
+          end
+        end
+
+        opt.separator "CONFIG OPTIONS:"
+
+        opt.on '-f', '--format NAME', 'report format' do |name|
+          runner.format = name
+        end
+        opt.on '-y', '--tapy', 'shortcut for -f tapy' do
+          runner.format = 'tapy'
+        end
+        opt.on '-j', '--tapj', 'shortcut for -f tapj' do
+          runner.format = 'tapj'
+        end
+
+        opt.on '-t', '--tag TAG', 'select tests by tag' do |tag|
+          runner.tags << tag
+        end
+        opt.on '-u', '--unit TAG', 'select tests by software unit' do |unit|
+          runner.units << unit
+        end
+        opt.on '-m', '--match TEXT', 'select tests by description' do |text|
+          runner.match << text 
+        end
+
+        opt.on '-I', '--loadpath PATH',  'add to $LOAD_PATH' do |paths|
+          paths.split(/[:;]/).reverse_each do |path|
+            $LOAD_PATH.unshift path
+          end
+        end
+        opt.on '-r', '--require FILE', 'require file' do |file|
+          require file
+        end
+        opt.on '-v' , '--verbose', 'provide extra detailed report' do
+          runner.verbose = true
+        end
+        #opt.on('--log DIRECTORY', 'log directory'){ |dir|
+        #  options[:log] = dir
+        #}
+        opt.on_tail("--[no-]ansi" , 'turn on/off ANSI colors'){ |v| $ansi = v }
+        opt.on_tail("--debug" , 'turn on debugging mode'){ $DEBUG = true }
+        #opt.on_tail("--about" , 'display information about lemon'){
+        #  puts "Ruby Test v#{VERSION}"
+        #  puts "#{COPYRIGHT}"
+        #  exit
+        #}
+        opt.on_tail('-h', '--help', 'display this help message'){
+          puts opt
+          exit
+        }
+      end.parse!(argv)
+
+      default.call(runner) if default && !config_loaded
+
+      runner.files.replace(argv) unless argv.empty?
+    end
+
+  end
+
+end

data/lib/rubytest/code_snippet.rb

@@ -0,0 +1,93 @@
+module Test
+
+  # Thanks goes to Suraj N. Kurapati for the origins of this code.
+  #
+  class CodeSnippet
+
+    def self.cache(file)
+      @cache ||= {}
+      @cache[file] ||=  File.exist?(file) ? File.readlines(file) : ['(N/A)']
+    end
+
+    #
+    def self.from_backtrace(backtrace)
+      backtrace.first =~ /(.+?):(\d+(?=:|\z))/ or return nil
+      file, line = $1, $2.to_i
+      new(file, line)
+    end
+
+    #
+    def self.from_error(exception)
+      backtrace = exception.backtrace
+      from_backtrace(backtrace)
+    end
+
+    #
+    def initialize(file, line)
+      @file = file
+      @line = line || 1
+      @code = CodeSnippet.cache(file)
+    end
+
+    #
+    attr :file
+
+    #
+    attr :line
+
+    #
+    attr :code
+
+    #
+    alias :source :code
+
+    #
+    def to_str
+      code[line-1].strip
+    end
+
+    #
+    #--
+    # TODO: ensure proper alignment by zero-padding line numbers
+    #++
+    def to_s(radius=2)
+      r = range(radius)
+      f = " %2s %0#{r.last.to_s.length}d %s"
+      r.map do |n|
+        f % [('=>' if n == line), n, code[n-1].chomp]
+      end.join("\n")
+    end
+
+    #
+    def to_a(radius=2)
+      r = range(radius)
+      r.map do |n|
+        code[n-1].chomp
+      end
+    end
+
+    #
+    def to_omap(radius=2)
+      a = []
+      r = range(radius)
+      r.each do |n|
+        a << {n => code[n-1].chomp}
+      end
+      a
+    end
+
+    #
+    def succ
+      line += 1
+    end
+
+  private
+
+    #
+    def range(radius)
+      [line - radius, 1].max..[line + radius, source.length].min
+    end
+
+  end
+
+end

data/lib/rubytest/config.rb

@@ -0,0 +1,106 @@
+module Test
+
+  #
+  def self.run(name=:default, &block)
+    @config ||= {}
+    @config[name.to_s] = block
+  end
+
+  def self.config
+    @config ||= {}
+  end
+
+  #
+  class Config
+
+    # Test configuration file.
+    #
+    # The name of the file is an ode to the original Ruby cli test tool.
+    #
+    # @example
+    #   .test
+    #   .testrb
+    #   .test.rb
+    #   .config/test.rb
+    #
+    # @todo Too many options for ruby-test configuration file.
+    GLOB_RC = '{.testrb,.test.rb,.test,.config/test.rb,config/test.rb}'
+
+    #
+    GLOB_ROOT = '{.ruby,.git,.hg}'
+
+    #
+    def self.load
+      super(rc_file) if rc_file
+      #Ruth.module_eval(File.read(rc_file)) if rc_file
+    end
+
+    # Find rc file.
+    def self.rc_file
+      @rc_file ||= (
+        glob    = GLOB_RC
+        stop    = root
+        default = nil
+        dir     = Dir.pwd
+        file    = nil
+        loop do
+          file = Dir[File.join(dir, glob)].first
+          break file if file
+          break if dir == stop
+          dir = File.dirname(dir)
+          break if dir == '/'
+        end
+        file ? file : default
+      )
+    end
+
+    # Find and cache project root directory.
+    #
+    # @return [String] Project's root path.
+    def self.root
+      @root ||= (
+        glob    = GLOB_ROOT
+        stop    = '/'
+        default = Dir.pwd
+        dir     = Dir.pwd
+        until dir == stop
+          break dir if Dir[File.join(dir, glob)].first
+          dir = File.dirname(dir)
+        end
+        dir == stop ? default : dir
+      )
+    end
+
+    # Load and cache a project's `.ruby` file.
+    #
+    # @return [Hash] Project's loaded `.ruby` file, if it has one.
+    def self.dotruby
+      @dotruby ||= (
+        drfile = File.join(root, '.ruby')
+        if File.exist?(drfile)
+          YAML.load_file(drfile)
+        else
+          {}
+        end
+      )
+    end
+
+    # Setup $LOAD_PATH based on .ruby file.
+    #
+    # @todo Maybe we should not fallback to typical load path?
+    def self.load_path_setup
+      if load_paths = dotruby['load_path']
+        load_paths.each do |path|
+          $LOAD_PATH.unshift(File.join(root, path))
+        end
+      else
+        typical_load_path = File.join(root, 'lib')
+        if File.directory?(typical_load_path)
+          $LOAD_PATH.unshift(typical_load_path) 
+        end
+      end
+    end
+
+  end
+
+end

data/lib/rubytest/core_ext/assertion.rb

@@ -0,0 +1,30 @@
+class Assertion < Exception
+
+  # New assertion (failure).
+  #
+  # @param message [String] the failure message
+  # @param options [Hash] options such as :backtrace
+  #
+  def initialize(message=nil, options={})
+    super(message)
+    backtrace = options[:backtrace]
+    set_backtrace(backtrace) if backtrace
+    @assertion = true
+  end
+
+  # Technically any object that affirmatively responds to #assertion?
+  # can be taken to be an Assertion. This makes it easier for various 
+  # libraries to work together without having to depend upon a common
+  # Assertion base class.
+  def assertion?
+    true # @assertion
+  end
+
+  # Parents error message prefixed with "(assertion)".
+  #
+  # @return [String] error message
+  def to_s
+    '(assertion) ' + super
+  end
+
+end

data/lib/rubytest/core_ext/exception.rb

@@ -0,0 +1,8 @@
+class Exception
+  def set_assertion(boolean)
+    @assertion = boolean
+  end
+  def assertion?
+    @assertion
+  end
+end