test-spec 0.2 → 0.3.0

data/{README.txt → README}

@@ -1,6 +1,6 @@
 = test/spec, a BDD interface for Test::Unit
 
-Copyright (C) 2006  Christian Neukirchen <mailto:chneukirchen@gmail.com>
+Copyright (C) 2006, 2007  Christian Neukirchen <mailto:chneukirchen@gmail.com>
 
 
 == What is test/spec?
@@ -95,6 +95,56 @@ If you write an useful general-purpose assertion, I'd like to hear of
 it and may add it to the test/spec distribution.
 
 
+== Messaging/Blaming
+
+With more complex assertions, it may be helpful to provide a message
+to show if the assertion has failed.  This can be done with the
+Should#blaming or Should#messaging methods:
+
+    RUBY_VERSION.should.messaging("Ruby too old.").be > "1.8.4"
+
+    (1 + 1).should.blaming("weird math").not.equal 11
+
+
+== Custom shoulds ("Matchers")
+
+To capture recurring patterns in parts of your specifications, you can
+define custom "shoulds" (RSpec calls them "matchers") in your
+contexts, or include modules of them:
+
+    context "Numbers"
+      class EqualString < Test::Spec::CustomShould
+        def matches?(other)
+          object == other.to_s
+        end
+      end
+    
+      def equal_string(str)
+        EqualString.new(str)
+      end
+    
+      specify "should have to_s"
+        42.should equal_string("42")
+      end
+    end
+
+Alternatively, your implementation can define
+CustomShould#assumptions, where you can use test/spec assertions
+instead of Boolean predicates:
+
+    class EqualString < Test::Spec::CustomShould
+      def assumptions(other)
+        object.should.equal other.to_s
+      end
+    end
+
+A CustomShould by default takes one argument, which is placed in
+self.object for your convenience.
+
+You can CustomShould#failure_message to provide a better error
+message.
+
+
 == SpecDox and RDox
 
 test/spec adds two additional test runners to Test::Unit, based on the
@@ -130,6 +180,13 @@ SpecDox and RDox work for Test::Unit too:
     3 specifications (30 requirements), 0 failures
 
 
+== Disabled specifications
+
+Akin to the usual Test::Unit practice, tests quickly can be disabled
+by replacing +specify+ with +xspecify+.  test/spec will count the
+disabled tests when you run it with SpecDox or RDox.
+
+
 == specrb
 
 Since version 0.2, test/spec features a standalone test runner called
@@ -151,6 +208,18 @@ plain Test::Unit suites, too.
 Run <tt>specrb --help</tt> for the usage.
 
 
+== Installing with RubyGems
+
+Since version 0.3, a Gem of test/spec is available.  You can install with:
+
+    gem install test-spec
+
+I also provide a local mirror of the gems (and development snapshots)
+at my site:
+
+    gem install test-spec --source http://chneukirchen.org/releases/gems
+
+
 == History
 
 * September 29th, 2006: First public release 0.1.
@@ -163,6 +232,18 @@ Run <tt>specrb --help</tt> for the usage.
   * Nested contexts
   * Standalone test/spec runner, specrb
 
+* January 24th, 2007: Third public release 0.3.
+  * should.be_close, should.be_an_instance_of, should.be_a_kind_of,
+    and should.be_nil have been deprecated.  Use the dot-variants of
+    them.  These assertions will be removed in 1.0.
+  * specrb -a now includes -Ilib by default for easier out-of-the-box
+    testing.
+  * Added custom shoulds.
+  * Added messaging/blaming.
+  * Added disabling of specifications.
+  * Small bug fixes.
+  * Gem available.
+
 
 == Contact
 
@@ -176,6 +257,8 @@ http://chneukirchen.org/repos/testspec
 == Thanks to
 
 * Eero Saynatkari for writing <tt>should.output</tt>.
+* Jean-Michel Garnier for packaging the first gem.
+* Mikko Lehtonen for testing the gem.
 * Thomas Fuchs for script.aculo.us BDD testing which convinced me.
 * Dave Astels for BDD.
 * The RSpec team for API inspiration.
@@ -184,7 +267,7 @@ http://chneukirchen.org/repos/testspec
 
 == Copying
 
-Copyright (C) 2006  Christian Neukirchen <http://purl.org/net/chneukirchen>
+Copyright (C) 2006, 2007  Christian Neukirchen <http://purl.org/net/chneukirchen>
 
 test/spec is licensed under the same terms as Ruby itself.
 

data/ROADMAP

@@ -0,0 +1 @@
+Version 1.0 (February 2006):: first stable release.

data/Rakefile

@@ -1,55 +1,6 @@
 # Rakefile for testspec.  -*-ruby-*-
-# 
-# 
-# 
-require 'rubygems'
-require 'rake'
-require 'rake/clean'
-require 'rake/testtask'
-require 'rake/packagetask'
-require 'rake/gempackagetask'
 require 'rake/rdoctask'
-require 'rake/contrib/rubyforgepublisher'
-require 'fileutils'
-require 'hoe'
-include FileUtils
-require File.join(File.dirname(__FILE__), 'lib', 'test-spec', 'version')
-
-AUTHOR = "Christian Neukirchen"  # can also be an array of Authors
-EMAIL = "chneukirchen@gmail.com"
-DESCRIPTION = "Behaviour Driven Development with Test::Unit"
-GEM_NAME = "test-spec" # what ppl will type to install your gem
-RUBYFORGE_PROJECT = "test-spec" # The unix name for your project
-HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
-RELEASE_TYPES = %w( gem ) # can use: gem, tar, zip
-
-
-NAME = "test-spec"
-REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
-VERS = ENV['VERSION'] || (TestSpec::VERSION::STRING + (REV ? ".#{REV}" : ""))
-CLEAN.include ['**/.*.sw?', '*.gem', '.config']
-RDOC_OPTS = ['--quiet', '--title', "test_spec documentation",
-    "--opname", "index.html",
-    "--line-numbers", 
-    "--main", "README",
-    "--inline-source"]
-
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-hoe = Hoe.new(GEM_NAME, VERS) do |p|
-  p.author = AUTHOR 
-  p.description = DESCRIPTION
-  p.email = EMAIL
-  p.summary = DESCRIPTION
-  p.url = HOMEPATH
-  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
-  p.test_globs = ["test/**/*_test.rb"]
-  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
-  p.extra_deps = ['flexmock','>= 0.4.3'],['mocha','>= 0.3.2']
-  # == Optional
-  #p.changes        - A description of the release's latest changes.
-  #p.spec_extras    - A hash of extra values to set in the gemspec.
-end
+require 'rake/testtask'
 
 
 desc "Run all the tests"
@@ -59,15 +10,36 @@ desc "Do predistribution stuff"
 task :predist => [:chmod, :changelog, :rdoc]
 
 
-desc "Run all the tests"
-task :test => :chmod do
-  ruby "bin/specrb -Ilib:test -w #{ENV['TEST'] || '-a'} #{ENV['TESTOPTS']}"
-end
-
 desc "Make an archive as .tar.gz"
 task :dist => :test do
   system "export DARCS_REPO=#{File.expand_path "."}; " +
-         "darcs dist -d testspec#{get_darcs_tree_version}"
+         "darcs dist -d test-spec#{get_darcs_tree_version}"
+end
+
+# Helper to retrieve the "revision number" of the darcs tree.
+def get_darcs_tree_version
+  return ""  unless File.directory? "_darcs"
+
+  changes = `darcs changes`
+  count = 0
+  tag = "0.0"
+  
+  changes.each("\n\n") { |change|
+    head, title, desc = change.split("\n", 3)
+    
+    if title =~ /^  \*/
+      # Normal change.
+      count += 1
+    elsif title =~ /tagged (.*)/
+      # Tag.  We look for these.
+      tag = $1
+      break
+    else
+      warn "Unparsable change: #{change}"
+    end
+  }
+
+  "-" + tag + "." + count.to_s
 end
 
 desc "Make binaries executable"
@@ -80,10 +52,78 @@ task :changelog do
   system "darcs changes --repo=#{ENV["DARCS_REPO"] || "."} >ChangeLog"
 end
 
+
+desc "Generate RDox"
+task "SPECS" do
+  ruby "bin/specrb -Ilib:test -a --rdox >SPECS"
+end
+
+
+begin
+  # To generate the gem, run "rake package"
+
+  $" << "sources"  if defined? FromSrc
+  require 'rubygems'
+
+  require 'rake'
+  require 'rake/clean'
+  require 'rake/packagetask'
+  require 'rake/gempackagetask'
+  require 'rake/contrib/rubyforgepublisher'
+  require 'fileutils'
+  require 'hoe'
+rescue LoadError
+  # Too bad.
+
+  desc "Run all the tests"
+  task :test => :chmod do
+    ruby "bin/specrb -Ilib:test -w #{ENV['TEST'] || '-a'} #{ENV['TESTOPTS']}"
+  end
+
+else
+  
+  RDOC_OPTS = ['--title', "test/spec documentation",
+               "--opname", "index.html",
+               "--line-numbers", 
+               "--main", "README",
+               "--inline-source"]
+  
+  # Generate all the Rake tasks
+  # Run 'rake -T' to see list of generated tasks (from gem root directory)
+  hoe = Hoe.new("test-spec", get_darcs_tree_version[1..-1]) do |p|
+    p.author = "Christian Neukirchen"
+    p.description = "a Behaviour Driven Development interface for Test::Unit"
+    p.email = "chneukirchen@gmail.com"
+    p.summary = <<EOF
+test/spec layers an RSpec-inspired interface on top of Test::Unit, so
+you can mix TDD and BDD (Behavior-Driven Development).
+
+test/spec is a clean-room implementation that maps most kinds of
+Test::Unit assertions to a `should'-like syntax.
+EOF
+    p.url = "http://test-spec.rubyforge.org"
+    p.test_globs = ["test/**/{test,spec}_*.rb"]
+    p.clean_globs = []
+    p.extra_deps = ['flexmock','>= 0.4.1'],['mocha','>= 0.3.2']
+    p.need_tar = false          # we do that ourselves
+    p.changes = File.read("README")[/^== History\n(.*?)^==/m, 1].
+                                    split(/\n{2,}/).last
+  end
+
+  task :package => ["Manifest.txt", :dist]
+
+  # Yes, this is ridiculous.
+  hoe.spec.dependencies.delete_if { |dep| dep.name == "hoe" }
+  Rake.application.instance_variable_get(:@tasks).delete :docs
+  Rake.application.instance_variable_get(:@tasks).delete "doc/index.html"
+  task :docs => :rdoc
+end
+
+
 desc "Generate RDoc documentation"
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_dir = "rdoc"
+  rdoc.rdoc_dir = "doc"
   rdoc.rdoc_files.include 'README'
   rdoc.rdoc_files.include 'ROADMAP'
   rdoc.rdoc_files.include 'SPECS'
@@ -91,47 +131,21 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
 end
 task :rdoc => "SPECS"
 
-desc "Generate RDox"
-task "SPECS" do
-  ruby "bin/specrb -Ilib:test -a --rdox >SPECS"
+
+desc "Generate Manifest.txt"
+task "Manifest.txt" do
+  system "darcs query manifest | sed 's:^./::' >Manifest.txt"
 end
 
 begin
   require 'rcov/rcovtask'
   
   Rcov::RcovTask.new do |t|
-    t.test_files = FileList['test/spec_*.rb'] + ['--', '-rs']   # evil
+    t.test_files = FileList['test/{spec,test}_*.rb'] + ['--', '-rs']   # evil
     t.verbose = true     # uncomment to see the executed command
-    t.rcov_opts = ["--text-report", "--include-file", "^lib\\|^test"]
+    t.rcov_opts = ["--text-report",
+                   "--include-file", "^lib,^test",
+                   "--exclude-only", "^/usr,^/home/.*/src"]
   end
 rescue LoadError
 end
-
-
-# Helper to retrieve the "revision number" of the darcs tree.
-def get_darcs_tree_version
-  return ""  unless File.directory? "_darcs"
-
-  changes = `darcs changes`
-  count = 0
-  tag = "0.0"
-  
-  changes.each("\n\n") { |change|
-    head, title, desc = change.split("\n", 3)
-    
-    if title =~ /^  \*/
-      # Normal change.
-      count += 1
-    elsif title =~ /tagged (.*)/
-      # Tag.  We look for these.
-      tag = $1
-      break
-    else
-      warn "Unparsable change: #{change}"
-    end
-  }
-
-  "-" + tag + "." + count.to_s
-end
-
-          

data/TODO

@@ -0,0 +1,2 @@
+- see ROADMAP
+- better handling of .should outside of specify(?)

data/bin/specrb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# -*- ruby -*-
+
+require 'optparse'
+
+testrbargv = []
+automatic = false
+
+opts = OptionParser.new("", 24, '  ') { |opts|
+  opts.banner = "Usage: specrb [options] [files | -a] [-- untouched arguments]"
+
+  opts.separator ""
+  opts.separator "Ruby options:"
+
+  lineno = 1
+  opts.on("-e", "--eval LINE", "evaluate a LINE of code") { |line|
+    eval line, TOPLEVEL_BINDING, "-e", lineno
+    lineno += 1
+  }
+
+  opts.on("-d", "--debug", "set debugging flags (set $DEBUG to true)") {
+    $DEBUG = true
+  }
+  opts.on("-w", "--warn", "turn warnings on for your script") {
+    $-w = true
+  }
+
+  opts.on("-I", "--include PATH",
+          "specify $LOAD_PATH (may be used more than once)") { |path|
+    $LOAD_PATH.unshift *path.split(":")
+  }
+
+  opts.on("-r", "--require LIBRARY",
+          "require the library, before executing your script") { |library|
+    require library
+  }
+
+  opts.separator ""
+  opts.separator "test/spec options:"
+
+  opts.on("-s", "--specdox", "do AgileDox-like output") {
+    testrbargv << "--runner=specdox"
+  }
+  opts.on("--rdox", "do AgileDox-like output with RDoc formatting") {
+    testrbargv << "--runner=rdox"
+  }
+
+  opts.on("-a", "--automatic", "gather tests from ./test/, include ./lib/") {
+    $LOAD_PATH.unshift "lib"  if File.directory? "lib"
+    automatic = true
+  }
+
+  opts.separator ""
+  opts.separator "test/unit options:"
+
+  opts.on('-n', '--name NAME', String,
+          "runs tests matching regexp NAME") { |n|
+    testrbargv << "-n" << "/#{n}/"
+  }
+  
+  opts.on('-t', '--testcase TESTCASE', String,
+          "runs tests in TestCases matching regexp TESTCASE") { |t|
+    testrbargv << "-t" << "/#{t}/"
+  }
+
+  opts.separator ""
+  opts.separator "Common options:"
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on_tail("--version", "Show version") do
+    require 'test/spec'
+    puts "specrb #{Test::Spec::VERSION}"
+    exit
+  end
+
+  opts.parse! ARGV
+}
+
+files = ARGV
+
+if automatic
+  files.concat Dir["test/test_*.rb"]
+  files.concat Dir["test/spec_*.rb"]
+  files.concat Dir["spec/spec_*.rb"]
+end
+
+if files.empty?
+  puts opts.banner
+  exit 1
+end
+
+argv = testrbargv + ["--"] + files
+
+require 'test/spec'
+
+Test::Unit.run = false
+runner = Test::Unit::AutoRunner.new true
+runner.process_args(argv) ||
+  abort("internal error calling Test::Unit, please report a bug")
+exit runner.run