baretest 0.1.0

data/MANIFEST.txt

@@ -0,0 +1,38 @@
+MANIFEST.txt
+README.markdown
+bin/baretest
+examples/test.rake
+examples/test.rb
+lib/test.rb
+lib/test/assertion.rb
+lib/test/assertion/failure.rb
+lib/test/assertion/support.rb
+lib/test/debug.rb
+lib/test/irb_mode.rb
+lib/test/run.rb
+lib/test/run/cli.rb
+lib/test/run/errors.rb
+lib/test/run/interactive.rb
+lib/test/run/minimal.rb
+lib/test/run/spec.rb
+lib/test/run/tap.rb
+lib/test/run/xml.rb
+lib/test/suite.rb
+lib/test/version.rb
+test/external/bootstraptest.rb
+test/external/bootstrapwrap.rb
+test/helper/mocks.rb
+test/lib/test.rb
+test/lib/test/assertion.rb
+test/lib/test/assertion/support.rb
+test/lib/test/debug.rb
+test/lib/test/irb_mode.rb
+test/lib/test/run.rb
+test/lib/test/run/cli.rb
+test/lib/test/run/errors.rb
+test/lib/test/run/interactive.rb
+test/lib/test/run/spec.rb
+test/lib/test/run/tap.rb
+test/lib/test/run/xml.rb
+test/lib/test/suite.rb
+test/setup.rb

data/README.markdown

@@ -0,0 +1,229 @@
+Bare Test
+=========
+
+
+
+Summary
+-------
+
+A minimal Testframework.
+Three methods to use it, Twenty to master it, about hundred lines of code[1].
+Bare Test, try it and you'll love it.
+
+
+
+Description
+-----------
+
+Baretest is a Testframework that tries to stay out of your way, but support you when you want it.
+In order to do so it has a load of features:
+
+* Strightforward and terse assertions (just a block whose return value defines
+  success/failure)
+* Easy grouping of assertions into suites
+* BDD style specifications/test descriptions (NOT code), also extractable
+* Uncomplicated dependency testing and skipping
+* Helpers to deal painlessly with raising, throwing, float imprecision,
+  unordered collections etc.
+* Ships with colored Shell formatter, Diagnostic-, Interactive-, XML- and TAP
+  formatter
+* Interactive formatter - drops you into an irb session within failed assertion
+  with all setup methods executed, so you can inspect interactively why it
+  failed.
+* Trivial to add new formatters (the standard formatters are only roughly 20-50
+  lines of code each)
+* Teardown and Setup for suites
+* Callbacks to integrate mock libraries
+* API to use it from code, such as rake tasks (comes with an example rake-task)
+* baretest executable to run tests on multiple files at once
+* Diagnostic assertion helpers (e.g. same(:a, :b) will give you 'Expected
+  :a but got :b' as diagnostic)
+
+
+
+Quick Try
+---------
+
+1. Download from github and unpack (or clone)
+2. Change into the baretest directory: `cd the/baretest/directory`
+3. Run the examples: `./bin/baretest examples/test.rb`
+
+That's it. Alternatively you can run baretests own tests, and play with formatters:
+`./bin/baretest -f tap`
+
+Unfortunately the installer and gem installer aren't ready yet.
+
+
+
+Executable
+----------
+
+    Usage: baretest [options] [glob, ...]
+    Glob defaults to 'test/**/*.rb'
+    Providing a directory as glob is equivalent to dir/**/*.rb
+    Options:
+      -f, --format FORMAT      use FORMAT for output
+      -F, --formats            show available formats
+      -d, --debug              set debugging flags (set $DEBUG to true)
+      -i, --interactive        drop into IRB on error or failure
+      -s, --setup FILE         specify setup file
+      -v, --version            print the version and exit
+      -w, --warn               turn warnings on for your script
+
+
+
+Planned Features
+----------------
+
+* --fail-all flag, to test/review diagnostics of tests
+* Word-wrapping for CLI runner
+* Flags for color and verbose (\[no-]color and \[no-]verbose) for the executable
+* Passing on flags/options for formatters
+* Alternative CLI runner with status implicit via colored/bg-colored descriptions
+* Alternative CLI runner which prints the name of the test prior the label and rewrites
+  the line when the test has executed to add status & coloring.
+* Simple stubbing with automatic cleanup at teardown. Example:
+
+        assert "Should require a single file listed in :requires option." do |a|
+          file = 'foo/bar'
+          stub(Kernel, :require) do |file, *args| a.touch(file) end
+          ::Test::Suite.create(nil, nil, :requires => file)
+        
+          touched file
+        end
+
+* Inline tests via Module#describe (basically the same as Test::Suite#suite)
+* YARD code to extract the specifications without running the code
+* A redmine plugin
+
+
+
+Rejected Features
+-----------------
+
+* Currently none
+
+
+A Bit of Background
+-------------------
+
+Originally, bare-test started out as a project for shits & giggles on the flight
+back from vegas (railsconf09), to prove that it is possible to have a fully
+fledged test-framework in under 100 lines of source-code.
+Later I realized that this project could become more. For one it was (still is)
+dead simple to add another formatter, it is just as dead simple to embedd it
+in code.
+The principles are trivial to understand, embrace and extend.
+Upon that it dawned me, that the project was viable and I began adding features
+not found in other projects.
+
+
+
+Example Testsuite
+-----------------
+
+From examples/test.rb:
+
+    Test.run_if_mainfile do
+      # assertions and refutations can be grouped in suites. They will share
+      # setup and teardown
+      # they don't have to be in suites, though
+      suite "Success" do
+        assert "An assertion returning a trueish value (non nil/false) is a success" do
+          true
+        end
+      end
+
+      suite "Failure" do
+        assert "An assertion returning a falsish value (nil/false) is a failure" do
+          false
+        end
+      end
+
+      suite "Pending" do
+        assert "An assertion without a block is pending"
+      end
+
+      suite "Error" do
+        assert "Uncaught exceptions in an assertion are an error" do
+          raise "Error!"
+        end
+      end
+
+      suite "Special assertions" do
+        assert "Assert a block to raise" do
+          raises do
+            sleep(rand()/3+0.05)
+            raise "If this raises then the assertion is a success"
+          end
+        end
+
+        assert "Assert a float to be close to another" do
+          a = 0.18 - 0.01
+          b = 0.17
+          within_delta a, b, 0.001
+        end
+
+        suite "Nested suite" do
+          assert "Assert two randomly ordered arrays to contain the same values" do
+            a = [*"A".."Z"] # an array with values from A to Z
+            b = a.sort_by { rand }
+            a.equal_unordered(b) # can be used with any Enumerable, uses hash-key identity
+          end
+        end
+      end
+
+      suite "Setup & Teardown" do
+        setup do
+          @foo = "foo"
+          @bar = "bar"
+        end
+
+        assert "@foo should be set" do
+          @foo == "foo"
+        end
+
+        suite "Nested suite" do
+          setup do
+            @bar = "inner bar"
+            @baz = "baz"
+          end
+
+          assert "@foo is inherited" do
+            @foo == "foo"
+          end
+
+          assert "@bar is overridden" do
+            @bar == "inner bar"
+          end
+
+          assert "@baz is defined only for inner" do
+            @baz == "baz"
+          end
+        end
+
+        teardown do
+          @foo = nil # not that it'd make much sense, just to demonstrate
+        end
+      end
+
+      suite "Dependencies", :requires => ['foo', 'bar'] do
+        assert "Will be skipped, due to unsatisfied dependencies" do
+          raise "This code therefore will never be executed"
+        end
+      end
+    end
+
+
+
+Known bugs
+----------
+
+* touch/touched have to clean up after every Assertion#execute. Should use the mock hooks.
+
+
+
+Foot Notes
+----------
+[1]: "" The abbreviated form without support code and output formatters.
+        The normal code is expanded to more lines for readability.

data/bin/baretest

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+
+#--
+# Copyright 2009 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+# Make sure the right libs are loaded, tries plain 'test' first, then a rubygem 'test', then
+# the relative path it'd be if it isn't installed at all and you're just testrunning it.
+require 'optparse'
+begin
+  require 'test'
+rescue LoadError
+  begin
+    require 'rubygems'
+    require 'test'
+  rescue LoadError
+    $LOAD_PATH.unshift(File.expand_path("#{__FILE__}/../../lib"))
+    require 'test'
+  end
+end
+
+
+
+# Get all the command-line arguments and adapt options to it
+format      = ENV['FORMAT'] || 'cli'
+interactive = ['false', nil].include?(ENV['INTERACTIVE']) ? false : true
+setup_path  = nil
+
+opts = OptionParser.new("", 24, '  ') do |opts|
+  opts.banner = "Usage: baretest [options] [glob, ...]"
+
+  opts.separator "Glob defaults to 'test/**/*.rb'"
+  opts.separator "Providing a directory as glob is equivalent to dir/**/*.rb\n"
+  opts.separator "Options:"
+
+  opts.on("-f", "--format FORMAT", "use FORMAT for output") { |use|
+    format = use
+  }
+
+  opts.on("-F", "--formats", "show available formats") { |use|
+    Dir.glob("{#{$LOAD_PATH.join(',')}}/test/run/*.rb") { |path|
+      puts "- #{File.basename(path, '.rb')}"
+    }
+    exit
+  }
+
+  opts.on("-d", "--debug", "set debugging flags (set $DEBUG to true)") {
+    $DEBUG = true
+  }
+
+  opts.on("-i", "--interactive", "drop into IRB on error or failure") {
+    interactive = true
+  }
+
+  opts.on("-s", "--setup FILE", "specify setup file") { |path|
+    setup_path = path
+  }
+
+  opts.on("-v", "--version", "print the version and exit") {
+    puts "baretest version 0.2"
+    exit
+  }
+
+  opts.on("-w", "--warn", "turn warnings on for your script") {
+    $VERBOSE = true
+  }
+
+  opts.parse! ARGV
+end
+
+
+
+# Load the setup file, all helper files and all test files
+if ARGV.empty? then
+  setup_path ||= 'test/setup.rb'
+  load(setup_path) if File.exist?(setup_path)
+  Dir.glob('test/lib/**/*.rb') { |path|
+    helper_path = path.sub(%r{^test/lib/}, 'test/helper/')
+    puts "Loading helper file #{helper_path}" if $VERBOSE
+    load(helper_path) if File.exist?(helper_path)
+    puts "Loading test file #{path}" if $VERBOSE
+    load(path)
+  }
+else
+  load(setup_path) if setup_path && File.exist?(setup_path)
+  ARGV.each { |path|
+    if File.directory?(path) then
+      Dir.glob("#{path}/**/*.rb") { load(path) }
+    else
+      Dir.glob(path) { load(path) }
+    end
+  }
+end
+
+
+
+# Run the tests
+Test.run(:format => format, :interactive => interactive)

data/examples/test.rake

@@ -0,0 +1,37 @@
+# This rake task expects to be in PROJECT_DIR/tasks/test.rake
+# It assumes that the tests are in PROJECT_DIR/test/**/*.rb
+# This is relevant as it calculates the paths accordingly.
+# Additionally it will add PROJECT_DIR/lib - if present - to $LOAD_PATH.
+
+desc "Run testsuite. Set FORMAT env variable to change the formatter used."
+task :test do
+	begin
+		require 'test'
+	rescue LoadError => e
+		puts "Could not run tests: #{e}"
+	else
+		# Prepare paths
+		rake_file = File.expand_path(__FILE__)
+		test_dir  = File.expand_path("#{rake_file}/../../test")
+		lib_dir   = File.expand_path("#{rake_file}/../../lib")
+
+		# Verify that the test directory exists
+		raise "Could not determine test directory, please adapt this rake task to " \
+					"your directory structure first." unless File.directory?(test_dir)
+
+		# Add PROJECT_DIR/lib to $LOAD_PATH if the dir exists
+		if File.directory?(lib_dir) && !$LOAD_PATH.include?(lib_dir) then
+			$LOAD_PATH.unshift(lib_dir)
+			puts "Added '#{lib_dir}' to $LOAD_PATH" if $VERBOSE
+		end
+
+		# Load all test definitions
+		Dir.glob(File.expand_path("#{test_dir}/**/*.rb")) { |path|
+			require path
+		}
+
+		# Run all tests
+		formatter = ENV["FORMAT"] || 'cli'
+		Test.run.run(formatter)
+	end
+end

data/examples/test.rb

@@ -0,0 +1,93 @@
+require 'test'
+
+
+
+Test.run_if_mainfile do
+	# assertions and refutations can be grouped in suites. They will share
+	# setup and teardown
+	# they don't have to be in suites, though
+	suite "Success" do
+		assert "An assertion returning a trueish value (non nil/false) is a success" do
+			true
+		end
+	end
+
+	suite "Failure" do
+		assert "An assertion returning a falsish value (nil/false) is a failure" do
+			false
+		end
+	end
+
+	suite "Pending" do
+		assert "An assertion without a block is pending"
+	end
+
+	suite "Error" do
+		assert "Uncaught exceptions in an assertion are an error" do
+			raise "Error!"
+		end
+	end
+
+	suite "Special assertions" do
+		assert "Assert a block to raise" do
+			raises do
+				sleep(rand()/3+0.05)
+				raise "If this raises then the assertion is a success"
+			end
+		end
+
+		assert "Assert a float to be close to another" do
+			a = 0.18 - 0.01
+			b = 0.17
+			within_delta a, b, 0.001
+		end
+
+		suite "Nested suite" do
+			assert "Assert two randomly ordered arrays to contain the same values" do
+				a = [*"A".."Z"] # an array with values from A to Z
+				b = a.sort_by { rand }
+				equal_unordered(a, b) # can be used with any Enumerable, uses hash-key identity
+			end
+		end
+	end
+
+	suite "Setup & Teardown" do
+		setup do
+			@foo = "foo"
+			@bar = "bar"
+		end
+
+		assert "@foo should be set" do
+			@foo == "foo"
+		end
+
+		suite "Nested suite" do
+			setup do
+				@bar = "inner bar"
+				@baz = "baz"
+			end
+
+			assert "@foo is inherited" do
+				@foo == "foo"
+			end
+
+			assert "@bar is overridden" do
+				@bar == "inner bar"
+			end
+
+			assert "@baz is defined only for inner" do
+				@baz == "baz"
+			end
+		end
+
+		teardown do
+			@foo = nil # not that it'd make much sense, just to demonstrate
+		end
+	end
+
+	suite "Dependencies", :requires => ['foo', 'bar'] do
+		assert "Will be skipped, due to unsatisfied dependencies" do
+			failure "Why the heck do you have a 'foo/bar' file?"
+		end
+	end
+end

data/lib/test/assertion/failure.rb

@@ -0,0 +1,14 @@
+#--
+# Copyright 2009 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+module Test
+  class Assertion
+    class Failure < StandardError
+    end
+  end
+end