rspec 0.4.0 → 0.5.0

data/CHANGES

@@ -1,22 +1,17 @@
 = RSpec Changelog
 
-== Explanation of this file:
- 
-* This document should be updated for every commit.
+== Version 0.5.0
 
-* The first section of each version (until the lines starting with a *)
-  will be used in the release notes' summary as well
-  as in the news posted on rubyforge. Therefore,
-  make sure it is a sentence that makes sense to the reader.
-  It should summarise the release at a high level.
-
-* Make sure the PKG_VERSION constant in Rakefile.rb is
-  consistent with the latest version in this document.
+This release introduces a new API and obsoletes previous versions
+* Lots and lots of changes. See examples.
 
 == Version 0.4.0
 
-The "two Daves walked into a bar" release.
+The "two Daves walked into a bar and Aslak ruined the party" release.
 
+* Moved source code to separate subfolders
+* Added new DSL runner based on instance_exec
+* Added spike for testdox/rdoc generation
 * merge Astels' and Chelimsky's work on ShouldHelper
 * this would be 0.5.0 if I updated the documentation
 * it breaks all of your existing specifications.  We're not sorry.

data/Rakefile

@@ -7,6 +7,8 @@ require 'rake/contrib/xforge'
 require 'rake/clean'
 require 'rake/testtask'
 require 'rake/rdoctask'
+require 'lib/spec/version'
+require 'lib/spec/rake/spectask'
 
 PKG_NAME = "rspec"
 # Versioning scheme: MAJOR.MINOR.PATCH
@@ -19,7 +21,7 @@ PKG_NAME = "rspec"
 # (This is subject to change - AH)
 #
 # REMEMBER TO KEEP PKG_VERSION IN SYNC WITH CHANGELOG
-PKG_VERSION = "0.4.0"
+PKG_VERSION   = Spec::VERSION::STRING
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 PKG_FILES = FileList[
   '[A-Z]*',
@@ -29,23 +31,26 @@ PKG_FILES = FileList[
   'doc/**/*'
 ]
 
-task :default => [:test, :test_text_runner]
+task :default => [:test] #, :test_text_runner]
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['examples/**/*_spec.rb']
+  t.verbose = true
+end
 
 Rake::TestTask.new do |t|
   t.libs << "test"
-  t.test_files = FileList['**/*_test.rb'].exclude("test/*_collector_test.rb",
-		"test/rspec_*.rb", "test/text_runner_test.rb")
+  t.test_files = FileList['test/**/*_test.rb']
   t.verbose = true
 end
 
 # text runner tests need to run individually
-
-Rake::TestTask.new(:test_text_runner) do |t|
-	t.libs << "test"
-	t.libs << "examples"
-	t.test_files = FileList['test/text_runner_test.rb']
-	t.verbose = true
-end
+#Rake::TestTask.new(:test_text_runner) do |t|
+#	t.libs << "test"
+#	t.libs << "examples"
+#	t.test_files = FileList['test/text_runner_test.rb']
+#	t.verbose = true
+#end
 
 
 # Create a task to build the RDOC documentation tree.
@@ -95,7 +100,7 @@ spec = Gem::Specification.new do |s|
   s.autorequire = 'spec'
 
   s.bindir = "bin"
-  s.executables = ["spec"]
+  s.executables = ["spec", "test2rspec"]
   s.default_executable = "spec"
 
   #### Author and project details.

data/TUTORIAL

@@ -236,7 +236,7 @@ includes "Star Wars", you will get the following error:
 
     1)
     <#<MovieList:0x284c1e0 @movies={"Star Wars"=>#<Movie:0x284c180 @name="Star Wars"
-    >}>> should include <"Space Balls"> (Spec::Exceptions::ExpectationNotMetError)
+    >}>> should include <"Space Balls"> (Spec::Api::ExpectationNotMetError)
     ./movie_spec.rb:34:in `should_include_space_balls'
     ../bin/spec:10
 

data/WHY_RSPEC

@@ -0,0 +1,115 @@
+== Why RSpec
+
+=== Readability
+RSpec specifications read better than Test::Unit tests. Compare this:
+
+  class TemperatureCoverterTest < Test::Unit::TestCase
+    def test_converts_0C_to_32F
+      c = TemperatureCoverter.new
+      assert_equal(32.0, c.convert_from_c_to_f(0.0)
+    end
+
+    def test_converts_100C_to_100F
+      c = TemperatureCoverter.new
+      assert_equal(212.0, c.convert_from_c_to_f(100.0)
+    end
+  end
+
+to this:
+
+  context "TemperatureCoverter"
+    specify "Converts 0C to 32F"
+      c = TemperatureCoverter.new
+      c.convert_from_c_to_f(0.0).should.equal 32.0
+    end
+
+    specify "Converts 100C to 212F"
+      c = TemperatureCoverter.new
+      c.convert_from_c_to_f(100.0).should.equal 212.0
+    end
+  end
+
+=== Built-in mocks
+....
+
+=== Self-documenting
+RSpec specifications are self documenting. If run with the --rspec-report option,
+it will produce the following report:
+
+== TemperatureCoverter
+* Converts 0C to 32F
+* Converts 100C to 212F
+
+RSpec reports gives a high-level overview of how the classes
+in the system should behave. Of course, the developers have to
+name their specifications appropriately.
+
+By making RSpec reports visible as part of the API documentation,
+developers are likely to put a little effort into making the RSpec
+report make sense. Consider this example (translated from an
+imaginary Test::Unit test):
+
+  context "TemperatureCoverter"
+    specify "Convert"
+      c = TemperatureCoverter.new
+      c.convert_from_c_to_f(0.0).should.equal 32.0
+      c.convert_from_c_to_f(100.0).should.equal 212.0
+    end
+  end
+
+And the generated report:
+
+== TemperatureCoverter
+* Convert
+
+This specification was translated from a Test::Unit file that has one test method,
+<tt>test_onvert</tt>. It doesn't read so well, and it doesn't convey much high-leve
+information about how the TemperatureCoverter class is supposed to behave. RSpec 
+encourages developers to give specifications a name that conveys the intent of the
+specification. This in turn has several subtle benefits:
+
+* Specifications tend to become smaller
+* It tends to higlight too coupled code (specification names become complex)
+
+It is the developers' responsibility to make sure that the name of each specification
+represent at a high level what is being assumed in the specification body.
+
+== What about my existing Test::Unit tests?
+RSpec comes with a migration tool that will translate all of your existing
+Test::Unit tests to RSpec specifications.
+
+== How do I run RSpec specifications?
+
+There are several ways to do this.
+
+=== Just run the ruby file
+Any RSpec specification is stand-alone and can be run with:
+
+  ruby path/to/my/spec.rb
+  
+This will run your spec and output the results to stdout. You can use command line options
+to tell RSpec to output documentation to a specific file too:
+
+  ruby path/to/my/spec.rb --rspec-report doc/rspec_report.rd
+
+=== Use the spec commandline
+You can run several specifications with:
+
+  spec path/to/my/directory
+  
+or 
+  
+  spec path/to/my/directory --rspec-report doc/rspec_report.rd
+  
+=== Use Rake
+RSpec ships with a task similar that lets you run RSpec specifications
+from Rake. Just upt the following in your Rakefile:
+
+  Rake::RSpecTask.new
+
+This will create a task called <tt>spec</tt> task that you can run like this:
+
+  rake spec
+  
+By default this will run all the specifications under the spec directory. See
+the Rake::RSpecTask documentation for details on how to override the defaults.

data/bin/spec

@@ -1,10 +1,23 @@
 #!/usr/bin/env ruby
 
-require 'spec'
+if ARGV.empty?
+  puts "You must provide a directory or file to run"
+  exit
+end
+
+require 'find'
+require File.dirname(__FILE__) + "/../lib/spec"
+
+context_runner = Spec::Runner::ContextRunner.new(ARGV)
+Spec::Runner::Context.context_runner = context_runner
 
 ARGV.each do |file|
-  require file
+  Find.find(file) do |path|
+    if FileTest.file?(path) and File.extname(path) == '.rb'
+      require path
+    end
+  end
 end
 
-runner = Spec::TextRunner.new
-runner.run
+context_runner.run
+

data/bin/test2rspec

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+require 'find'
+require 'ostruct'
+require 'optparse'
+require File.dirname(__FILE__) + "/../lib/spec/tool/command_line.rb"
+require File.dirname(__FILE__) + "/../lib/spec/tool/test_unit_translator.rb"
+
+opts = OptionParser.new do |opts|
+  opts.banner = "Usage: test2rspec [options] SRC [DEST]"
+  opts.separator ""
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+end
+opts.parse!(ARGV)
+
+cl = Spec::Tool::CommandLine.new
+source = ARGV[0]
+target = ARGV[1]
+
+if source.nil?
+  STDERR.puts opts
+  exit 1
+end
+
+begin
+  cl.run source, target, STDOUT
+rescue => e
+  STDERR.puts e.message
+  STDERR.puts e.backtrace.join("\n")
+  STDERR.puts opts
+end

data/examples/airport_spec.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + '/../lib/spec'
+
+class Airport
+  def working?
+    true
+  end
+  
+  def need?(thing)
+    thing != :cables
+  end
+end
+
+context "Airport at home" do
+  setup do
+    @airport = Airport.new
+  end
+  
+  specify "should always work" do
+    @airport.should.be.working
+  end
+
+  specify "should not need cables" do
+    @airport.should.not.need :cables
+  end
+
+  specify "should not need electricity" do
+    # This will fail...
+    @airport.should.not.need :electricity
+  end
+  
+  teardown do
+    @airport = nil
+  end
+
+end

data/examples/mocking_spec.rb

@@ -0,0 +1,16 @@
+require File.dirname(__FILE__) + '/../lib/spec'
+
+context "Mocker" do
+
+  specify "should be able to call mock()" do
+    mock = mock("poke me")
+    mock.should_receive(:poke)
+    mock.poke
+  end
+
+  specify "should fail when expected message not received" do
+    mock = mock("poke me")
+    mock.should_receive(:poke)
+  end
+
+end

data/examples/spec_framework_spec.rb

@@ -0,0 +1,28 @@
+require File.dirname(__FILE__) + '/../lib/spec'
+
+class SpecFramework
+  def intuitive?
+    true
+  end
+  
+  def adopted_quickly?
+    false
+  end
+end
+
+context "Spec framework" do
+
+  setup do
+    @spec_framework = SpecFramework.new
+  end
+  
+  specify "should be intuitive" do
+    @spec_framework.should.be.intuitive
+  end
+
+  specify "should be adopted quickly" do
+    #this will fail
+    @spec_framework.should.be.adopted_quickly
+  end
+
+end

data/examples/stack.rb

@@ -0,0 +1,36 @@
+class StackUnderflowError < RuntimeError
+end
+
+class StackOverflowError < RuntimeError
+end
+
+class Stack
+  
+  def initialize
+    @items = []
+  end
+  
+  def push object
+    raise StackOverflowError if @items.length == 10
+    @items.push object
+  end
+  
+  def pop
+    raise StackUnderflowError if @items.empty?
+    @items.delete @items.last
+  end
+  
+  def top
+    raise StackUnderflowError if @items.empty?
+    @items.last
+  end
+  
+  def empty?
+    @items.empty?
+  end
+  
+  def size
+    @items.length
+  end
+  
+end

data/examples/stack_spec.rb

@@ -0,0 +1,112 @@
+context "An empty stack" do
+  
+  setup do
+    @stack = Stack.new
+  end
+  
+  specify "should accept an item when sent push" do
+    lambda { @stack.push Object.new }.should.not.raise
+  end
+  
+  specify "should complain when sent top" do
+    lambda { @stack.top }.should.raise StackUnderflowError
+  end
+  
+  specify "should complain when sent pop" do
+    lambda { @stack.pop }.should.raise StackUnderflowError
+  end
+  
+end
+
+context "A stack with one item" do
+  setup do
+    @stack = Stack.new
+    @stack.push 3
+  end
+
+  specify "should accept an item when sent push" do
+    lambda { @stack.push Object.new }.should.not.raise
+  end
+  
+  specify "should return top when sent top" do
+    @stack.top.should.be 3
+  end
+  
+  specify "should not remove top when sent top" do
+    @stack.top.should.be 3
+    @stack.top.should.be 3
+  end
+  
+  specify "should return top when sent pop" do
+    @stack.pop.should.be 3
+  end
+  
+  specify "should remove top when sent pop" do
+    @stack.pop.should.be 3
+    lambda { @stack.pop }.should.raise StackUnderflowError
+  end
+  
+end
+
+context "An almost full stack (with one item less than capacity)" do
+  setup do
+    @stack = Stack.new
+    (1..9).each { |i| @stack.push i }
+  end
+
+  specify "should accept an item when sent push" do
+    @stack.push Object.new
+  end
+  
+  specify "should return top when sent top" do
+    @stack.top.should.be 9
+  end
+  
+  specify "should not remove top when sent top" do
+    @stack.top.should.be 9
+    @stack.top.should.be 9
+  end
+  
+  specify "should return top when sent pop" do
+    @stack.pop.should.be 9
+  end
+  
+  specify "should remove top when sent pop" do
+    @stack.pop.should.be 9
+    @stack.pop.should.be 8
+  end
+  
+end
+context "A full stack" do
+  
+  setup do
+    @stack = Stack.new
+    (1..10).each { |i| @stack.push i }
+  end
+
+  specify "should complain on push" do
+    lambda { @stack.push Object.new }.should.raise StackOverflowError
+  end
+  
+  specify "should return top when sent top" do
+    @stack.top.should.be 10
+  end
+  
+  specify "should not remove top when sent top" do
+    @stack.top.should.be 10
+    @stack.top.should.be 10
+  end
+  
+  specify "should return top when sent pop" do
+    @stack.pop.should.be 10
+  end
+  
+  specify "should remove top when sent pop" do
+    @stack.pop.should.be 10
+    @stack.pop.should.be 9
+  end
+  
+end
+
+
+