robert-shoulda 2.10.3

data/lib/shoulda/context.rb

@@ -0,0 +1,413 @@
+module Shoulda
+  class << self
+    attr_accessor :contexts
+    def contexts # :nodoc:
+      @contexts ||= []
+    end
+
+    def current_context # :nodoc:
+      self.contexts.last
+    end
+
+    def add_context(context) # :nodoc:
+      self.contexts.push(context)
+    end
+
+    def remove_context # :nodoc:
+      self.contexts.pop
+    end
+  end
+
+  module ClassMethods
+    # == Should statements
+    #
+    # Should statements are just syntactic sugar over normal Test::Unit test methods.  A should block
+    # contains all the normal code and assertions you're used to seeing, with the added benefit that
+    # they can be wrapped inside context blocks (see below).
+    #
+    # === Example:
+    #
+    #  class UserTest < Test::Unit::TestCase
+    #
+    #    def setup
+    #      @user = User.new("John", "Doe")
+    #    end
+    #
+    #    should "return its full name"
+    #      assert_equal 'John Doe', @user.full_name
+    #    end
+    #
+    #  end
+    #
+    # ...will produce the following test:
+    # * <tt>"test: User should return its full name. "</tt>
+    #
+    # Note: The part before <tt>should</tt> in the test name is gleamed from the name of the Test::Unit class.
+    #
+    # Should statements can also take a Proc as a <tt>:before </tt>option.  This proc runs after any
+    # parent context's setups but before the current context's setup.
+    #
+    # === Example:
+    #
+    #  context "Some context" do
+    #    setup { puts("I run after the :before proc") }
+    #
+    #    should "run a :before proc", :before => lambda { puts("I run before the setup") }  do
+    #      assert true
+    #    end
+    #  end
+
+    def should(name, options = {}, &blk)
+      if Shoulda.current_context
+        block_given? ? Shoulda.current_context.should(name, options, &blk) : Shoulda.current_context.should_eventually(name)
+      else
+        context_name = self.name.gsub(/Test/, "")
+        context = Shoulda::Context.new(context_name, self) do
+          block_given? ? should(name, options, &blk) : should_eventually(name)
+        end
+        context.build
+      end
+    end
+
+    # == Before statements
+    #
+    # Before statements are should statements that run before the current
+    # context's setup. These are especially useful when setting expectations.
+    #
+    # === Example:
+    #
+    #  class UserControllerTest < Test::Unit::TestCase
+    #    context "the index action" do
+    #      setup do
+    #        @users = [Factory(:user)]
+    #        User.stubs(:find).returns(@users)
+    #      end
+    #
+    #      context "on GET" do
+    #        setup { get :index }
+    #
+    #        should_respond_with :success
+    #
+    #        # runs before "get :index"
+    #        before_should "find all users" do
+    #          User.expects(:find).with(:all).returns(@users)
+    #        end
+    #      end
+    #    end
+    #  end
+    def before_should(name, &blk)
+      should(name, :before => blk) { assert true }
+    end
+
+    # Just like should, but never runs, and instead prints an 'X' in the Test::Unit output.
+    def should_eventually(name, options = {}, &blk)
+      context_name = self.name.gsub(/Test/, "")
+      context = Shoulda::Context.new(context_name, self) do
+        should_eventually(name, &blk)
+      end
+      context.build
+    end
+
+    # == Contexts
+    #
+    # A context block groups should statements under a common set of setup/teardown methods.
+    # Context blocks can be arbitrarily nested, and can do wonders for improving the maintainability
+    # and readability of your test code.
+    #
+    # A context block can contain setup, should, should_eventually, and teardown blocks.
+    #
+    #  class UserTest < Test::Unit::TestCase
+    #    context "A User instance" do
+    #      setup do
+    #        @user = User.find(:first)
+    #      end
+    #
+    #      should "return its full name"
+    #        assert_equal 'John Doe', @user.full_name
+    #      end
+    #    end
+    #  end
+    #
+    # This code will produce the method <tt>"test: A User instance should return its full name. "</tt>.
+    #
+    # Contexts may be nested.  Nested contexts run their setup blocks from out to in before each
+    # should statement.  They then run their teardown blocks from in to out after each should statement.
+    #
+    #  class UserTest < Test::Unit::TestCase
+    #    context "A User instance" do
+    #      setup do
+    #        @user = User.find(:first)
+    #      end
+    #
+    #      should "return its full name"
+    #        assert_equal 'John Doe', @user.full_name
+    #      end
+    #
+    #      context "with a profile" do
+    #        setup do
+    #          @user.profile = Profile.find(:first)
+    #        end
+    #
+    #        should "return true when sent :has_profile?"
+    #          assert @user.has_profile?
+    #        end
+    #      end
+    #    end
+    #  end
+    #
+    # This code will produce the following methods
+    # * <tt>"test: A User instance should return its full name. "</tt>
+    # * <tt>"test: A User instance with a profile should return true when sent :has_profile?. "</tt>
+    #
+    # <b>Just like should statements, a context block can exist next to normal <tt>def test_the_old_way; end</tt>
+    # tests</b>.  This means you do not have to fully commit to the context/should syntax in a test file.
+
+    def context(name, &blk)
+      if Shoulda.current_context
+        Shoulda.current_context.context(name, &blk)
+      else
+        context = Shoulda::Context.new(name, self, &blk)
+        context.build
+      end
+    end
+
+    # Returns the class being tested, as determined by the test class name.
+    #
+    #   class UserTest; described_type; end
+    #   # => User
+    def described_type
+      self.name.gsub(/Test$/, '').constantize
+    end
+
+    # Sets the return value of the subject instance method:
+    #
+    #   class UserTest < Test::Unit::TestCase
+    #     subject { User.first }
+    #
+    #     # uses the existing user
+    #     should_validate_uniqueness_of :email
+    #   end
+    def subject(&block)
+      @subject_block = block
+    end
+
+    def subject_block # :nodoc:
+      @subject_block
+    end
+  end
+
+  module InstanceMethods
+    # Returns an instance of the class under test.
+    #
+    #   class UserTest
+    #     should "be a user" do
+    #       assert_kind_of User, subject # passes
+    #     end
+    #   end
+    #
+    # The subject can be explicitly set using the subject class method:
+    #
+    #   class UserTest
+    #     subject { User.first }
+    #     should "be an existing user" do
+    #       assert !subject.new_record? # uses the first user
+    #     end
+    #   end
+    #
+    # If an instance variable exists named after the described class, that
+    # instance variable will be used as the subject. This behavior is
+    # deprecated, and will be removed in a future version of Shoulda. The
+    # recommended approach for using a different subject is to use the subject
+    # class method.
+    #
+    #   class UserTest
+    #     should "be the existing user" do
+    #       @user = User.new
+    #       assert_equal @user, subject # passes
+    #     end
+    #   end
+    #
+    # The subject is used by all macros that require an instance of the class
+    # being tested.
+    def subject
+      @shoulda_subject ||= construct_subject
+    end
+
+    def subject_block # :nodoc:
+      (@shoulda_context && @shoulda_context.subject_block) || self.class.subject_block
+    end
+
+    def get_instance_of(object_or_klass) # :nodoc:
+      if object_or_klass.is_a?(Class)
+        klass = object_or_klass
+        ivar = "@#{instance_variable_name_for(klass)}"
+        if instance = instance_variable_get(ivar)
+          warn "[WARNING] Using #{ivar} as the subject. Future versions " <<
+               "of Shoulda will require an explicit subject using the " <<
+               "subject class method. Add this after your setup to avoid " <<
+               "this warning: subject { #{ivar} }"
+          instance
+        else
+          klass.new
+        end
+      else
+        object_or_klass
+      end
+    end
+
+    def instance_variable_name_for(klass) # :nodoc:
+      klass.to_s.split('::').last.underscore
+    end
+
+    private
+
+    def construct_subject
+      if subject_block
+        instance_eval(&subject_block)
+      else
+        get_instance_of(self.class.described_type)
+      end
+    end
+  end
+
+  class Context # :nodoc:
+
+    attr_accessor :name               # my name
+    attr_accessor :parent             # may be another context, or the original test::unit class.
+    attr_accessor :subcontexts        # array of contexts nested under myself
+    attr_accessor :setup_blocks       # blocks given via setup methods
+    attr_accessor :teardown_blocks    # blocks given via teardown methods
+    attr_accessor :shoulds            # array of hashes representing the should statements
+    attr_accessor :should_eventuallys # array of hashes representing the should eventually statements
+    attr_accessor :subject_block
+
+    def initialize(name, parent, &blk)
+      Shoulda.add_context(self)
+      self.name               = name
+      self.parent             = parent
+      self.setup_blocks       = []
+      self.teardown_blocks    = []
+      self.shoulds            = []
+      self.should_eventuallys = []
+      self.subcontexts        = []
+
+      merge_block(&blk)
+      Shoulda.remove_context
+    end
+
+    def merge_block(&blk)
+      blk.bind(self).call
+    end
+
+    def context(name, &blk)
+      self.subcontexts << Context.new(name, self, &blk)
+    end
+
+    def setup(&blk)
+      self.setup_blocks << blk
+    end
+
+    def teardown(&blk)
+      self.teardown_blocks << blk
+    end
+
+    def should(name, options = {}, &blk)
+      if block_given?
+        self.shoulds << { :name => name, :before => options[:before], :block => blk }
+      else
+       self.should_eventuallys << { :name => name }
+     end
+    end
+
+    def should_eventually(name, &blk)
+      self.should_eventuallys << { :name => name, :block => blk }
+    end
+
+    def subject(&block)
+      self.subject_block = block
+    end
+
+    def subject_block
+      return @subject_block if @subject_block
+      parent.subject_block
+    end
+
+    def full_name
+      parent_name = parent.full_name if am_subcontext?
+      return [parent_name, name].join(" ").strip
+    end
+
+    def am_subcontext?
+      parent.is_a?(self.class) # my parent is the same class as myself.
+    end
+
+    def test_unit_class
+      am_subcontext? ? parent.test_unit_class : parent
+    end
+
+    def create_test_from_should_hash(should)
+      test_name = ["test:", full_name, "should", "#{should[:name]}. "].flatten.join(' ').to_sym
+
+      if test_unit_class.instance_methods.include?(test_name.to_s)
+        warn "  * WARNING: '#{test_name}' is already defined"
+      end
+
+      context = self
+      test_unit_class.send(:define_method, test_name) do
+        @shoulda_context = context
+        begin
+          context.run_parent_setup_blocks(self)
+          should[:before].bind(self).call if should[:before]
+          context.run_current_setup_blocks(self)
+          should[:block].bind(self).call
+        ensure
+          context.run_all_teardown_blocks(self)
+        end
+      end
+    end
+
+    def run_all_setup_blocks(binding)
+      run_parent_setup_blocks(binding)
+      run_current_setup_blocks(binding)
+    end
+
+    def run_parent_setup_blocks(binding)
+      self.parent.run_all_setup_blocks(binding) if am_subcontext?
+    end
+
+    def run_current_setup_blocks(binding)
+      setup_blocks.each do |setup_block|
+        setup_block.bind(binding).call
+      end
+    end
+
+    def run_all_teardown_blocks(binding)
+      teardown_blocks.reverse.each do |teardown_block|
+        teardown_block.bind(binding).call
+      end
+      self.parent.run_all_teardown_blocks(binding) if am_subcontext?
+    end
+
+    def print_should_eventuallys
+      should_eventuallys.each do |should|
+        test_name = [full_name, "should", "#{should[:name]}. "].flatten.join(' ')
+        puts "  * DEFERRED: " + test_name
+      end
+    end
+
+    def build
+      shoulds.each do |should|
+        create_test_from_should_hash(should)
+      end
+
+      subcontexts.each { |context| context.build }
+
+      print_should_eventuallys
+    end
+
+    def method_missing(method, *args, &blk)
+      test_unit_class.send(method, *args, &blk)
+    end
+
+  end
+end

data/lib/shoulda/helpers.rb

@@ -0,0 +1,8 @@
+module Shoulda # :nodoc:
+  module Helpers
+    # Prints a message to stdout, tagged with the name of the calling method.
+    def report!(msg = "")
+      puts("#{caller.first}: #{msg}")
+    end
+  end
+end

data/lib/shoulda/macros.rb

@@ -0,0 +1,133 @@
+require 'shoulda/private_helpers'
+
+module Shoulda # :nodoc:
+  module Macros
+    # Macro that creates a test asserting a change between the return value
+    # of a block that is run before and after the current setup block
+    # is run. This is similar to Active Support's <tt>assert_difference</tt>
+    # assertion, but supports more than just numeric values.  See also
+    # should_not_change.
+    #
+    # The passed description will be used when generating the test name and failure messages.
+    #
+    # Example:
+    #
+    #   context "Creating a post" do
+    #     setup { Post.create }
+    #     should_change("the number of posts", :by => 1) { Post.count }
+    #   end
+    #
+    # As shown in this example, the <tt>:by</tt> option expects a numeric
+    # difference between the before and after values of the expression.  You
+    # may also specify <tt>:from</tt> and <tt>:to</tt> options:
+    #
+    #   should_change("the number of posts", :from => 0, :to => 1) { Post.count }
+    #   should_change("the post title", :from => "old", :to => "new") { @post.title }
+    #
+    # Combinations of <tt>:by</tt>, <tt>:from</tt>, and <tt>:to</tt> are allowed:
+    #
+    #   # Assert the value changed in some way:
+    #   should_change("the post title") { @post.title }
+    #
+    #   # Assert the value changed to anything other than "old:"
+    #   should_change("the post title", :from => "old") { @post.title }
+    #
+    #   # Assert the value changed to "new:"
+    #   should_change("the post title", :to => "new") { @post.title }
+    def should_change(description, options = {}, &block)
+      by, from, to = get_options!([options], :by, :from, :to)
+      stmt = "change #{description}"
+      stmt << " from #{from.inspect}" if from
+      stmt << " to #{to.inspect}" if to
+      stmt << " by #{by.inspect}" if by
+
+      if block_given?
+        code = block
+      else
+        warn "[DEPRECATION] should_change(expression, options) is deprecated. " <<
+             "Use should_change(description, options) { code } instead."
+        code = lambda { eval(description) }
+      end
+      before = lambda { @_before_should_change = code.bind(self).call }
+      should stmt, :before => before do
+        old_value = @_before_should_change
+        new_value = code.bind(self).call
+        assert_operator from, :===, old_value, "#{description} did not originally match #{from.inspect}" if from
+        assert_not_equal old_value, new_value, "#{description} did not change" unless by == 0
+        assert_operator to, :===, new_value, "#{description} was not changed to match #{to.inspect}" if to
+        assert_equal old_value + by, new_value if by
+      end
+    end
+
+    # Macro that creates a test asserting no change between the return value
+    # of a block that is run before and after the current setup block
+    # is run. This is the logical opposite of should_change.
+    #
+    # The passed description will be used when generating the test name and failure message.
+    #
+    # Example:
+    #
+    #   context "Updating a post" do
+    #     setup { @post.update_attributes(:title => "new") }
+    #     should_not_change("the number of posts") { Post.count }
+    #   end
+    def should_not_change(description, &block)
+      if block_given?
+        code = block
+      else
+        warn "[DEPRECATION] should_not_change(expression) is deprecated. " <<
+             "Use should_not_change(description) { code } instead."
+        code = lambda { eval(description) }
+      end
+      before = lambda { @_before_should_not_change = code.bind(self).call }
+      should "not change #{description}", :before => before do
+        new_value = code.bind(self).call
+        assert_equal @_before_should_not_change, new_value, "#{description} changed"
+      end
+    end
+
+    # Macro that creates a test asserting that a record of the given class was
+    # created.
+    #
+    # Example:
+    #
+    #   context "creating a post" do
+    #     setup { Post.create(post_attributes) }
+    #     should_create :post
+    #   end
+    def should_create(class_name)
+      should_change_record_count_of(class_name, 1, 'create')
+    end
+
+    # Macro that creates a test asserting that a record of the given class was
+    # destroyed.
+    #
+    # Example:
+    #
+    #   context "destroying a post" do
+    #     setup { Post.first.destroy }
+    #     should_destroy :post
+    #   end
+    def should_destroy(class_name)
+      should_change_record_count_of(class_name, -1, 'destroy')
+    end
+
+    private
+
+    def should_change_record_count_of(class_name, amount, action) # :nodoc:
+      klass = class_name.to_s.camelize.constantize
+      before = lambda do
+        @_before_change_record_count = klass.count
+      end
+      human_name = class_name.to_s.humanize.downcase
+      should "#{action} a #{human_name}", :before => before do
+        assert_equal @_before_change_record_count + amount,
+                     klass.count,
+                     "Expected to #{action} a #{human_name}"
+      end
+    end
+
+    include Shoulda::Private
+  end
+end
+

data/lib/shoulda/private_helpers.rb

@@ -0,0 +1,13 @@
+module Shoulda # :nodoc:
+  module Private # :nodoc:
+    # Returns the values for the entries in the args hash who's keys are listed in the wanted array.
+    # Will raise if there are keys in the args hash that aren't listed.
+    def get_options!(args, *wanted)
+      ret  = []
+      opts = (args.last.is_a?(Hash) ? args.pop : {})
+      wanted.each {|w| ret << opts.delete(w)}
+      raise ArgumentError, "Unsupported options given: #{opts.keys.join(', ')}" unless opts.keys.empty?
+      return wanted.size == 1 ? ret.first : ret
+    end
+  end
+end

data/lib/shoulda/proc_extensions.rb

@@ -0,0 +1,14 @@
+# Stolen straight from ActiveSupport
+
+class Proc #:nodoc:
+  def bind(object)
+    block, time = self, Time.now
+    (class << object; self end).class_eval do
+      method_name = "__bind_#{time.to_i}_#{time.usec}"
+      define_method(method_name, &block)
+      method = instance_method(method_name)
+      remove_method(method_name)
+      method
+    end.bind(object)
+  end
+end

data/lib/shoulda/rails.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'active_support'
+require 'shoulda'
+
+require 'shoulda/active_record'     if defined? ActiveRecord::Base
+require 'shoulda/action_controller' if defined? ActionController::Base
+require 'shoulda/action_view'       if defined? ActionView::Base
+require 'shoulda/action_mailer'     if defined? ActionMailer::Base
+
+if defined?(RAILS_ROOT)
+  # load in the 3rd party macros from vendorized plugins and gems
+  Shoulda.autoload_macros RAILS_ROOT, File.join("vendor", "{plugins,gems}", "*")
+end

data/lib/shoulda/rspec.rb

@@ -0,0 +1,11 @@
+require 'shoulda/active_record/matchers'
+require 'shoulda/action_controller/matchers'
+require 'active_support/test_case'
+
+# :enddoc:
+module ActiveSupport
+  class TestCase
+    include Shoulda::ActiveRecord::Matchers
+    include Shoulda::ActionController::Matchers
+  end
+end

data/lib/shoulda/tasks/list_tests.rake

@@ -0,0 +1,29 @@
+namespace :shoulda do
+  desc "List the names of the test methods in a specification like format"
+  task :list do
+    $LOAD_PATH.unshift("test")
+
+    require 'test/unit'
+    require 'rubygems'
+    require 'active_support'
+
+    # bug in test unit.  Set to true to stop from running.
+    Test::Unit.run = true
+
+    test_files = Dir.glob(File.join('test', '**', '*_test.rb'))
+    test_files.each do |file|
+      load file
+      klass = File.basename(file, '.rb').classify
+      unless Object.const_defined?(klass.to_s)
+        puts "Skipping #{klass} because it doesn't map to a Class"
+        next
+      end
+      klass = klass.constantize
+
+      puts klass.name.gsub('Test', '')
+
+      test_methods = klass.instance_methods.grep(/^test/).map {|s| s.gsub(/^test: /, '')}.sort
+      test_methods.each {|m| puts "  " + m }
+    end
+  end
+end

data/lib/shoulda/tasks/yaml_to_shoulda.rake

@@ -0,0 +1,28 @@
+namespace :shoulda do
+  # From http://blog.internautdesign.com/2007/11/2/a-yaml_to_shoulda-rake-task
+  # David.Lowenfels@gmail.com
+  desc "Converts a YAML file (FILE=./path/to/yaml) into a Shoulda skeleton" 
+  task :from_yaml do
+    require 'yaml'
+    
+    def yaml_to_context(hash, indent = 0)
+      indent1 = '  ' * indent
+      indent2 = '  ' * (indent + 1)
+      hash.each_pair do |context, shoulds|
+        puts indent1 + "context \"#{context}\" do" 
+        puts    
+        shoulds.each do |should|
+          yaml_to_context( should, indent + 1 ) and next if should.is_a?( Hash )
+          puts indent2 + "should_eventually \"" + should.gsub(/^should +/,'') + "\" do" 
+          puts indent2 + "end" 
+          puts
+        end
+        puts indent1 + "end" 
+      end
+    end 
+    
+    puts("Please pass in a FILE argument.") and exit unless ENV['FILE']
+      
+    yaml_to_context( YAML.load_file( ENV['FILE'] ) )
+  end
+end

data/lib/shoulda/tasks.rb

@@ -0,0 +1,3 @@
+Dir[File.join(File.dirname(__FILE__), 'tasks', '*.rake')].each do |f|
+  load f
+end

data/lib/shoulda/test_unit.rb

@@ -0,0 +1,22 @@
+require 'test/unit'
+
+require 'shoulda/context'
+require 'shoulda/proc_extensions'
+require 'shoulda/assertions'
+require 'shoulda/macros'
+require 'shoulda/helpers'
+require 'shoulda/autoload_macros'
+require 'shoulda/rails' if defined? RAILS_ROOT
+
+module Test # :nodoc: all
+  module Unit
+    class TestCase
+      include Shoulda::InstanceMethods
+      extend Shoulda::ClassMethods
+      include Shoulda::Assertions
+      extend Shoulda::Macros
+      include Shoulda::Helpers
+    end
+  end
+end
+