baretest 0.1.0 → 0.2.3

data/LICENSE.txt

@@ -0,0 +1,52 @@
+The BareTest library is copyrighted free software by Stefan Rusterholz.
+You can redistribute it and/or modify it under the terms o the conditions
+below (also known as the 'Ruby License'):
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/MANIFEST.txt

@@ -1,38 +1,57 @@
+LICENSE.txt
 MANIFEST.txt
-README.markdown
+README.rdoc
 bin/baretest
+doc/baretest.rdoc
+doc/mocking_stubbing_test_doubles.rdoc
+doc/quickref.rdoc
+doc/writing_tests.rdoc
+examples/tests/irb_mode/failures.rb
+examples/tests/mock_developer/test/helper/mocks.rb
+examples/tests/mock_developer/test/setup.rb
+examples/tests/mock_developer/test/suite/mock_demo.rb
+examples/tests/overview/test.rb
+examples/tests/variations/variations_01.rb
+examples/tests/variations/variations_02.rb
+examples/tests/variations/variations_03.rb
 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
+lib/baretest.rb
+lib/baretest/assertion.rb
+lib/baretest/assertion/context.rb
+lib/baretest/assertion/failure.rb
+lib/baretest/assertion/skip.rb
+lib/baretest/assertion/support.rb
+lib/baretest/irb_mode.rb
+lib/baretest/layout.rb
+lib/baretest/mocha.rb
+lib/baretest/run.rb
+lib/baretest/run/cli.rb
+lib/baretest/run/errors.rb
+lib/baretest/run/minimal.rb
+lib/baretest/run/profile.rb
+lib/baretest/run/spec.rb
+lib/baretest/run/tap.rb
+lib/baretest/run/xml.rb
+lib/baretest/setup.rb
+lib/baretest/skipped.rb
+lib/baretest/skipped/assertion.rb
+lib/baretest/skipped/suite.rb
+lib/baretest/suite.rb
+lib/baretest/utilities.rb
+lib/baretest/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
+test/suite/lib/baretest.rb
+test/suite/lib/baretest/assertion.rb
+test/suite/lib/baretest/assertion/support.rb
+test/suite/lib/baretest/irb_mode.rb
+test/suite/lib/baretest/run.rb
+test/suite/lib/baretest/run/cli.rb
+test/suite/lib/baretest/run/errors.rb
+test/suite/lib/baretest/run/interactive.rb
+test/suite/lib/baretest/run/spec.rb
+test/suite/lib/baretest/run/tap.rb
+test/suite/lib/baretest/run/xml.rb
+test/suite/lib/baretest/suite.rb

data/README.rdoc

@@ -0,0 +1,260 @@
+= Bare Test
+
+
+
+== Summary
+
+A testframework that doesn't stand in your way or forces you to learn a new
+language. Two methods is all that is required to know.
+
+
+
+== Also See
+
+Executable Docs:: doc/baretest.rdoc
+IRC::             The channel #ruby-lang on irc.freenode.org
+                  
+                  I'm there under the nick apeiros.
+                  
+                  Beware, I'm idling there 24/7, so my nick being in there doesn't
+                  mean I'm in front of the computer.
+
+
+
+== 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:
+
+* Straightforward 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-, XML- and TAP formatter
+* Interactive mode - 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`
+
+
+
+== Install
+
+1. run `gem install baretest`, alternatively run `sudo gem install baretest`
+2. There is no 2.
+
+To get baretest edge, use:
+
+1. Download from github and unpack (or clone)
+2. Change into the baretest directory: `cd the/baretest/directory`
+3. Run the installation task: `rake gem:install` (alternatively `rake install:lib`)
+
+If you have multiple ruby versions installed parallely, this might pick the wrong gem
+executable to install the gem. You can set the GEM env variable to ensure it uses the
+right one: `rake gem:install GEM=gem1.9`
+
+
+
+== 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
+
+* Passing on flags/options for formatters
+* Tagging tests to allow focusing (only run tests with/without specific tags)
+* Word-wrapping for CLI runner
+* Flags for color and verbose (\[no-]color and \[no-]verbose) for the executable
+* baretest --init \[LAYOUT], to create the necessary directory structure
+* Detect whether baretest is run from an interactive terminal or not and adjust
+  defaults (no-color e.g.)
+* 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
+* --fail-all flag, to test/review diagnostics of tests (no idea how to do that yet)
+
+
+
+== 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:
+
+  BareTest.suite 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
+
+
+
+== Credits & Contributions
+
+* dominikh
+  * adding mocha integration
+  * showing me every dirty little bit I did wrong
+  * fixes
+  * added line number on failures
+
+
+
+== Known bugs
+
+Currently none.
+
+
+
+== Foot Notes
+<sup>1</sup>:: The abbreviated form without support code and output formatters.
+               The normal code is expanded to more lines for readability.

data/bin/baretest

@@ -8,19 +8,19 @@
 
 
 
-# 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.
+Version = "0.3.2"
+
+
+
 require 'optparse'
 begin
-  require 'test'
+  # if baretest is installed as a gem, the executable is be wrapped by rubgems anyway, so we don't
+  # need to require rubygems ourself.
+  require 'baretest'
 rescue LoadError
-  begin
-    require 'rubygems'
-    require 'test'
-  rescue LoadError
-    $LOAD_PATH.unshift(File.expand_path("#{__FILE__}/../../lib"))
-    require 'test'
-  end
+  # assume baretest is not installed and this is a cold-run from source
+  $LOAD_PATH.unshift(File.expand_path("#{__FILE__}/../../lib"))
+  require 'baretest'
 end
 
 
@@ -33,23 +33,80 @@ setup_path  = nil
 opts = OptionParser.new("", 24, '  ') do |opts|
   opts.banner = "Usage: baretest [options] [glob, ...]"
 
-  opts.separator "Glob defaults to 'test/**/*.rb'"
+  opts.separator "Glob defaults to 'test/{suite,unit,integration,system}/**/*.rb'"
   opts.separator "Providing a directory as glob is equivalent to dir/**/*.rb\n"
   opts.separator "Options:"
 
+  opts.on(nil, "--init", "create the necessary directories and files") {
+    core = %w[
+      test
+      test/external
+      test/helper
+      test/helper/suite
+      test/suite
+    ]
+    mirror = {
+      'bin'  => %w[test/helper/suite test/suite],
+      'lib'  => %w[test/helper/suite test/suite],
+      'rake' => %w[test/helper/suite test/suite],
+    }
+    files = {
+      'test/setup.rb' => <<-END_OF_SETUP.gsub(/^ {8}/, '')
+        $LOAD_PATH.unshift(File.expand_path("\#{__FILE__}/../../lib")) # Add PROJECT/lib to $LOAD_PATH
+      END_OF_SETUP
+    }
+
+    puts "Creating all directories and files needed in #{File.expand_path('.')}"
+    core.each do |dir|
+      if File.exist?(dir) then
+        puts "Directory #{dir} exists already -- skipping"
+      else
+        puts "Creating #{dir}"
+        Dir.mkdir(dir)
+      end
+    end
+    mirror.each do |path, destinations|
+      if File.exist?(path) then
+        destinations.each do |destination|
+          destination = File.join(destination,path)
+          if File.exist?(destination) then
+            puts "Mirror #{destination} of #{path} exists already -- skipping"
+          else
+            puts "Mirroring #{path} in #{destination}"
+            Dir.mkdir(destination)
+          end
+        end
+      end
+    end
+    files.each do |path, data|
+      if File.exist?(path) then
+        puts "File #{path} exists already -- skipping"
+      else
+        puts "Writing #{path}"
+        File.open(path, 'wb') do |fh|
+          fh.write(data)
+        end
+      end
+    end
+
+    exit
+  }
+
   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 "Available formats:"
+    Dir.glob("{#{$LOAD_PATH.join(',')}}/baretest/run/*.rb") { |path|
       puts "- #{File.basename(path, '.rb')}"
     }
     exit
   }
 
   opts.on("-d", "--debug", "set debugging flags (set $DEBUG to true)") {
-    $DEBUG = true
+    $DEBUG   = true
+    $VERBOSE = true
   }
 
   opts.on("-i", "--interactive", "drop into IRB on error or failure") {
@@ -61,7 +118,7 @@ opts = OptionParser.new("", 24, '  ') do |opts|
   }
 
   opts.on("-v", "--version", "print the version and exit") {
-    puts "baretest version 0.2"
+    puts "baretest executable version #{Version}, library version #{BareTest::VERSION}"
     exit
   }
 
@@ -76,15 +133,11 @@ 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)
-  }
+  BareTest.load_standard_test_files(
+    :verbose    => $VERBOSE,
+    :setup_path => setup_path,
+    :chdir      => '.'
+  )
 else
   load(setup_path) if setup_path && File.exist?(setup_path)
   ARGV.each { |path|
@@ -99,4 +152,9 @@ end
 
 
 # Run the tests
-Test.run(:format => format, :interactive => interactive)
+puts if $VERBOSE
+if BareTest.run(:format => format, :interactive => interactive).global_status == :success then
+  exit 0
+else
+  exit 1
+end

data/doc/baretest.rdoc

@@ -0,0 +1,98 @@
+= The baretest executable
+
+
+
+== 1. Usage
+
+Basic Usage:
+
+  baretest [options] [glob, ...]"
+
+Either you provide a `glob` (or a directory, which is equivalent to DIRECTORY/\*\*/\*.rb),
+then baretest will load all the files it matches and invoke BareTest.run in the end. Or you
+use the standard way and let baretest use convention. For that you should run baretest within
+the project, preferably the toplevel.
+Baretest will then search the directory tree upwards until it finds 'test/setup.rb'. It
+will then use the default layout of a project, which should look roughly like this:
+
+  |-- bin
+  |   `-- ...
+  |-- doc
+  |   `-- ...
+  |-- examples
+  |   `-- ...
+  |-- lib
+  |   `-- ...
+  |-- rake
+  |   `-- ...
+  `-- test
+      |-- external
+      |   `-- ...
+      |-- helper
+      |   `-- ...
+      |-- setup.rb
+      `-- suite
+          |-- bin
+          |   `-- ...
+          `-- lib
+              `-- ...
+
+The important part are the directories under 'test'. The directory 'test/suite' should mirror your
+project, but instead of the real files contain the files that test their counterparts. For example,
+the file 'YOURPROJECT/lib/yourproject.rb' has its tests in
+'YOURPROJECT/test/suite/lib/yourproject.rb'.
+Additionally, baretest will in that mode look for a file
+'YOURPROJECT/test/helper/suite/lib/yourproject.rb' and load it if found.
+
+
+
+== 2. Options
+
+
+=== Getting information about baretest:
+
+-F, \--formats:: Lists the available output formatters
+
+-v::             Prints the baretest executables and the libs version number
+
+
+=== Running tests:
+
+-i, \--interactive::   drop into IRB on error or failure
+                       
+-d, \--debug::         Set debugging flags.
+                       
+                       This sets $DEBUG to true, same as rubys -d switch.
+                       
+-f, \--format FORMAT:: Use the formatter specified in FORMAT, defaults to 'cli'
+                       
+-s, \--setup FILE::    specify setup file
+                       
+                       This option allows you to tell baretest where it finds the setup.rb file.
+                       
+                       Defaults to test/setup.rb.
+                       
+-w, \--warn::          Turn warnings on for your script.
+                       
+                       This sets $VERBOSE to true, same as rubys -w switch.
+                       
+                       Additionally, some formatters will provide more information
+                       (e.g. full backtraces on errors) when $VERBOSE is set.
+
+
+
+=== 3. The interactive mode
+
+In interactive mode, baretest will stop execution when an error or a failure is hit. It
+then prints out the status, the assertions description, its code and then drops you into
+an irb-shell in the context of the failed assertion, with setup already executed. You
+can then try out what caused the assertion to fail.
+
+Be aware that printing the code relies on your indentation.
+
+
+
+=== 4. Writing a formatter
+
+This section will follow. For now, just take a look at the existing formatters.
+They are pretty simple.

data/doc/mocking_stubbing_test_doubles.rdoc

@@ -0,0 +1,5 @@
+= Mocking, Stubbing and TestDoubles
+
+BareTest off-the-shelf provides currently only integration with mocha.
+You can use mocha (assuming you have installed the mocha gem) by requiring 'baretest/mocha'.
+Best you add that to your setup.rb.