HeSYINUvSBZfxqA-capistrano 2.5.21

data/test/configuration/actions/invocation_test.rb

@@ -0,0 +1,225 @@
+require "utils"
+require 'capistrano/configuration/actions/invocation'
+
+class ConfigurationActionsInvocationTest < Test::Unit::TestCase
+  class MockConfig
+    attr_reader :options
+    attr_accessor :debug
+    attr_accessor :dry_run
+		attr_accessor :preserve_roles
+
+    def initialize
+      @options = {}
+    end
+
+    def [](*args)
+      @options[*args]
+    end
+
+    def set(name, value)
+      @options[name] = value
+    end
+
+    def fetch(*args)
+      @options.fetch(*args)
+    end
+
+    include Capistrano::Configuration::Actions::Invocation
+  end
+
+  def setup
+    @config = MockConfig.new
+    @original_io_proc = MockConfig.default_io_proc
+    @config.stubs(:logger).returns(stub_everything)
+  end
+
+  def teardown
+    MockConfig.default_io_proc = @original_io_proc
+  end
+
+  def test_run_options_should_be_passed_to_execute_on_servers
+    @config.expects(:execute_on_servers).with(:foo => "bar")
+    @config.run "ls", :foo => "bar"
+  end
+
+  def test_run_will_return_if_dry_run
+    @config.expects(:dry_run).returns(true)
+    @config.expects(:execute_on_servers).never
+    @config.run "ls", :foo => "bar"
+  end
+
+  def test_add_default_command_options_should_return_bare_options_if_there_is_no_env_or_shell_specified
+    assert_equal({:foo => "bar"}, @config.add_default_command_options(:foo => "bar"))
+  end
+
+  def test_add_default_command_options_should_merge_default_environment_as_env
+    @config[:default_environment][:bang] = "baz"
+    assert_equal({:foo => "bar", :env => { :bang => "baz" }}, @config.add_default_command_options(:foo => "bar"))
+  end
+
+  def test_add_default_command_options_should_merge_env_with_default_environment
+    @config[:default_environment][:bang] = "baz"
+    @config[:default_environment][:bacon] = "crunchy"
+    assert_equal({:foo => "bar", :env => { :bang => "baz", :bacon => "chunky", :flip => "flop" }}, @config.add_default_command_options(:foo => "bar", :env => {:bacon => "chunky", :flip => "flop"}))
+  end
+
+  def test_add_default_command_options_should_use_default_shell_if_present
+    @config.set :default_shell, "/bin/bash"
+    assert_equal({:foo => "bar", :shell => "/bin/bash"}, @config.add_default_command_options(:foo => "bar"))
+  end
+
+  def test_add_default_command_options_should_use_default_shell_of_false_if_present
+    @config.set :default_shell, false
+    assert_equal({:foo => "bar", :shell => false}, @config.add_default_command_options(:foo => "bar"))
+  end
+
+  def test_add_default_command_options_should_use_shell_in_preference_of_default_shell
+    @config.set :default_shell, "/bin/bash"
+    assert_equal({:foo => "bar", :shell => "/bin/sh"}, @config.add_default_command_options(:foo => "bar", :shell => "/bin/sh"))
+  end
+
+  def test_default_io_proc_should_log_stdout_arguments_as_info
+    ch = { :host => "capistrano",
+           :server => server("capistrano"),
+           :options => { :logger => mock("logger") } }
+    ch[:options][:logger].expects(:info).with("data stuff", "out :: capistrano")
+    MockConfig.default_io_proc[ch, :out, "data stuff"]
+  end
+
+  def test_default_io_proc_should_log_stderr_arguments_as_important
+    ch = { :host => "capistrano",
+           :server => server("capistrano"),
+           :options => { :logger => mock("logger") } }
+    ch[:options][:logger].expects(:important).with("data stuff", "err :: capistrano")
+    MockConfig.default_io_proc[ch, :err, "data stuff"]
+  end
+
+  def test_sudo_should_default_to_sudo
+    @config.expects(:run).with("sudo -p 'sudo password: ' ls", {})
+    @config.sudo "ls"
+  end
+
+  def test_sudo_should_use_sudo_variable_definition
+    @config.expects(:run).with("/opt/local/bin/sudo -p 'sudo password: ' ls", {})
+    @config.options[:sudo] = "/opt/local/bin/sudo"
+    @config.sudo "ls"
+  end
+
+  def test_sudo_should_interpret_as_option_as_user
+    @config.expects(:run).with("sudo -p 'sudo password: ' -u app ls", {})
+    @config.sudo "ls", :as => "app"
+  end
+
+  def test_sudo_should_pass_options_through_to_run
+    @config.expects(:run).with("sudo -p 'sudo password: ' ls", :foo => "bar")
+    @config.sudo "ls", :foo => "bar"
+  end
+
+  def test_sudo_should_avoid_minus_p_when_sudo_prompt_is_empty
+    @config.set :sudo_prompt, ""
+    @config.expects(:run).with("sudo ls", {})
+    @config.sudo "ls"
+  end
+
+  def test_sudo_should_interpret_sudo_prompt_variable_as_custom_prompt
+    @config.set :sudo_prompt, "give it to me: "
+    @config.expects(:run).with("sudo -p 'give it to me: ' ls", {})
+    @config.sudo "ls"
+  end
+
+  def test_sudo_behavior_callback_should_send_password_when_prompted_with_default_sudo_prompt
+    ch = mock("channel")
+    ch.expects(:send_data).with("g00b3r\n")
+    @config.options[:password] = "g00b3r"
+    @config.sudo_behavior_callback(nil)[ch, nil, "sudo password: "]
+  end
+
+  def test_sudo_behavior_callback_should_send_password_when_prompted_with_custom_sudo_prompt
+    ch = mock("channel")
+    ch.expects(:send_data).with("g00b3r\n")
+    @config.set :sudo_prompt, "give it to me: "
+    @config.options[:password] = "g00b3r"
+    @config.sudo_behavior_callback(nil)[ch, nil, "give it to me: "]
+  end
+
+  def test_sudo_behavior_callback_with_incorrect_password_on_first_prompt
+    ch = mock("channel")
+    ch.stubs(:[]).with(:host).returns("capistrano")
+    ch.stubs(:[]).with(:server).returns(server("capistrano"))
+    @config.expects(:reset!).with(:password)
+    @config.sudo_behavior_callback(nil)[ch, nil, "Sorry, try again."]
+  end
+
+  def test_sudo_behavior_callback_with_incorrect_password_on_subsequent_prompts
+    callback = @config.sudo_behavior_callback(nil)
+
+    ch = mock("channel")
+    ch.stubs(:[]).with(:host).returns("capistrano")
+    ch.stubs(:[]).with(:server).returns(server("capistrano"))
+    ch2 = mock("channel")
+    ch2.stubs(:[]).with(:host).returns("cap2")
+    ch2.stubs(:[]).with(:server).returns(server("cap2"))
+
+    @config.expects(:reset!).with(:password).times(2)
+
+    callback[ch, nil, "Sorry, try again."]
+    callback[ch2, nil, "Sorry, try again."] # shouldn't call reset!
+    callback[ch, nil, "Sorry, try again."]
+  end
+
+  def test_sudo_behavior_callback_should_reset_password_and_prompt_again_if_output_includes_both_cues
+    ch = mock("channel")
+    ch.stubs(:[]).with(:host).returns("capistrano")
+    ch.stubs(:[]).with(:server).returns(server("capistrano"))
+    ch.expects(:send_data, "password!\n").times(2)
+
+    @config.set(:password, "password!")
+    @config.expects(:reset!).with(:password)
+
+    callback = @config.sudo_behavior_callback(nil)
+    callback[ch, :out, "sudo password: "]
+    callback[ch, :out, "Sorry, try again.\nsudo password: "]
+  end
+
+  def test_sudo_behavior_callback_should_defer_to_fallback_for_other_output
+    callback = @config.sudo_behavior_callback(inspectable_proc)
+
+    a = mock("channel", :called => true)
+    b = mock("stream", :called => true)
+    c = mock("data", :called => true)
+  
+    callback[a, b, c]
+  end
+
+  def test_invoke_command_should_default_to_run
+    @config.expects(:run).with("ls", :once => true)
+    @config.invoke_command("ls", :once => true)
+  end
+
+  def test_invoke_command_should_delegate_to_method_identified_by_via
+    @config.expects(:foobar).with("ls", :once => true)
+    @config.invoke_command("ls", :once => true, :via => :foobar)
+  end
+
+  private
+
+    def inspectable_proc
+      Proc.new do |ch, stream, data|
+        ch.called
+        stream.called
+        data.called
+      end
+    end
+
+    def prepare_command(command, sessions, options)
+      a = mock("channel", :called => true)
+      b = mock("stream", :called => true)
+      c = mock("data", :called => true)
+
+      compare_args = Proc.new do |tree, sess, opts|
+        tree.fallback.command == command && sess == sessions && opts == options
+      end
+
+      Capistrano::Command.expects(:process).with(&compare_args)
+    end
+end

data/test/configuration/callbacks_test.rb

@@ -0,0 +1,220 @@
+require "utils"
+require 'capistrano/configuration/callbacks'
+
+class ConfigurationCallbacksTest < Test::Unit::TestCase
+  class MockConfig
+    attr_reader :original_initialize_called
+    attr_reader :called
+
+    def initialize
+      @original_initialize_called = true
+      @called = []
+    end
+
+    def execute_task(task)
+      invoke_task_directly(task)
+    end
+
+    protected
+
+      def invoke_task_directly(task)
+        @called << task
+      end
+
+    include Capistrano::Configuration::Callbacks
+  end
+
+  def setup
+    @config = MockConfig.new
+    @config.stubs(:logger).returns(stub_everything("logger"))
+  end
+
+  def test_initialize_should_initialize_callbacks_collection
+    assert @config.original_initialize_called
+    assert @config.callbacks.empty?
+  end
+
+  def test_before_should_delegate_to_on
+    @config.expects(:on).with(:before, :foo, "bing:blang", {:only => :bar, :zip => :zing})
+    @config.before :bar, :foo, "bing:blang", :zip => :zing
+  end
+
+  def test_after_should_delegate_to_on
+    @config.expects(:on).with(:after, :foo, "bing:blang", {:only => :bar, :zip => :zing})
+    @config.after :bar, :foo, "bing:blang", :zip => :zing
+  end
+
+  def test_on_with_single_reference_should_add_task_callback
+    @config.on :before, :a_test
+    assert_equal 1, @config.callbacks[:before].length
+    assert_equal :a_test, @config.callbacks[:before][0].source
+    @config.expects(:find_and_execute_task).with(:a_test)
+    @config.callbacks[:before][0].call
+  end
+
+  def test_on_with_multi_reference_should_add_all_as_task_callback
+    @config.on :before, :first, :second, :third
+    assert_equal 3, @config.callbacks[:before].length
+    assert_equal %w(first second third), @config.callbacks[:before].map { |c| c.source.to_s }
+  end
+
+  def test_on_with_block_should_add_block_as_proc_callback
+    called = false
+    @config.on(:before) { called = true }
+    assert_equal 1, @config.callbacks[:before].length
+    assert_instance_of Proc, @config.callbacks[:before][0].source
+    @config.callbacks[:before][0].call
+    assert called
+  end
+
+  def test_on_with_single_only_should_set_only_as_string_array_on_all_references
+    @config.on :before, :first, "second:third", :only => :primary
+    assert_equal 2, @config.callbacks[:before].length
+    assert @config.callbacks[:before].all? { |c| c.only == %w(primary) }
+  end
+
+  def test_on_with_multi_only_should_set_only_as_string_array_on_all_references
+    @config.on :before, :first, "second:third", :only => [:primary, "other:one"]
+    assert_equal 2, @config.callbacks[:before].length
+    assert @config.callbacks[:before].all? { |c| c.only == %w(primary other:one) }
+  end
+
+  def test_on_with_single_except_should_set_except_as_string_array_on_all_references
+    @config.on :before, :first, "second:third", :except => :primary
+    assert_equal 2, @config.callbacks[:before].length
+    assert @config.callbacks[:before].all? { |c| c.except == %w(primary) }
+  end
+
+  def test_on_with_multi_except_should_set_except_as_string_array_on_all_references
+    @config.on :before, :first, "second:third", :except => [:primary, "other:one"]
+    assert_equal 2, @config.callbacks[:before].length
+    assert @config.callbacks[:before].all? { |c| c.except == %w(primary other:one) }
+  end
+
+  def test_on_with_only_and_block_should_set_only_as_string_array
+    @config.on(:before, :only => :primary) { blah }
+    assert_equal 1, @config.callbacks[:before].length
+    assert_equal %w(primary), @config.callbacks[:before].first.only
+  end
+
+  def test_on_with_except_and_block_should_set_except_as_string_array
+    @config.on(:before, :except => :primary) { blah }
+    assert_equal 1, @config.callbacks[:before].length
+    assert_equal %w(primary), @config.callbacks[:before].first.except
+  end
+  
+  def test_on_without_tasks_or_block_should_raise_error
+    assert_raises(ArgumentError) { @config.on(:before) }
+  end
+
+  def test_on_with_both_tasks_and_block_should_raise_error
+    assert_raises(ArgumentError) { @config.on(:before, :first) { blah } }
+  end
+
+  def test_trigger_without_constraints_should_invoke_all_callbacks
+    task = stub(:fully_qualified_name => "any:old:thing")
+    @config.on(:before, :first, "second:third")
+    @config.on(:after, :another, "and:another")
+    @config.expects(:find_and_execute_task).with(:first)
+    @config.expects(:find_and_execute_task).with("second:third")
+    @config.expects(:find_and_execute_task).with(:another).never
+    @config.expects(:find_and_execute_task).with("and:another").never
+    @config.trigger(:before, task)
+  end
+
+  def test_trigger_with_only_constraint_should_invoke_only_matching_callbacks
+    task = stub(:fully_qualified_name => "any:old:thing")
+    @config.on(:before, :first)
+    @config.on(:before, "second:third", :only => "any:old:thing")
+    @config.on(:before, "this:too", :only => "any:other:thing")
+    @config.on(:after, :another, "and:another")
+    @config.expects(:find_and_execute_task).with(:first)
+    @config.expects(:find_and_execute_task).with("second:third")
+    @config.expects(:find_and_execute_task).with("this:too").never
+    @config.expects(:find_and_execute_task).with(:another).never
+    @config.expects(:find_and_execute_task).with("and:another").never
+    @config.trigger(:before, task)
+  end
+
+  def test_trigger_with_except_constraint_should_invoke_anything_but_matching_callbacks
+    task = stub(:fully_qualified_name => "any:old:thing")
+    @config.on(:before, :first)
+    @config.on(:before, "second:third", :except => "any:old:thing")
+    @config.on(:before, "this:too", :except => "any:other:thing")
+    @config.on(:after, :another, "and:another")
+    @config.expects(:find_and_execute_task).with(:first)
+    @config.expects(:find_and_execute_task).with("second:third").never
+    @config.expects(:find_and_execute_task).with("this:too")
+    @config.expects(:find_and_execute_task).with(:another).never
+    @config.expects(:find_and_execute_task).with("and:another").never
+    @config.trigger(:before, task)
+  end
+
+  def test_trigger_without_task_should_invoke_all_callbacks_for_that_event
+    task = stub(:fully_qualified_name => "any:old:thing")
+    @config.on(:before, :first)
+    @config.on(:before, "second:third", :except => "any:old:thing")
+    @config.on(:before, "this:too", :except => "any:other:thing")
+    @config.on(:after, :another, "and:another")
+    @config.expects(:find_and_execute_task).with(:first)
+    @config.expects(:find_and_execute_task).with("second:third")
+    @config.expects(:find_and_execute_task).with("this:too")
+    @config.expects(:find_and_execute_task).with(:another).never
+    @config.expects(:find_and_execute_task).with("and:another").never
+    @config.trigger(:before)
+  end
+
+  def test_execute_task_without_named_hooks_should_just_call_task
+    ns = stub("namespace", :default_task => nil, :name => "old", :fully_qualified_name => "any:old")
+    task = stub(:fully_qualified_name => "any:old:thing", :name => "thing", :namespace => ns)
+
+    ns.stubs(:search_task).returns(nil)
+
+    @config.execute_task(task)
+    assert_equal [task], @config.called
+  end
+
+  def test_execute_task_with_named_before_hook_should_call_named_before_hook
+    ns = stub("namespace", :default_task => nil, :name => "old", :fully_qualified_name => "any:old")
+    task = stub(:fully_qualified_name => "any:old:thing", :name => "thing", :namespace => ns)
+    before_task = stub(:fully_qualified_name => "any:old:before_thing", :name => "before_thing", :namespace => ns)
+
+    ns.stubs(:search_task).returns(nil)
+    ns.expects(:search_task).with("before_thing").returns(before_task)
+
+    @config.execute_task(task)
+    assert_equal [before_task, task], @config.called
+  end
+
+  def test_execute_task_with_named_after_hook_should_call_named_after_hook
+    ns = stub("namespace", :default_task => nil, :name => "old", :fully_qualified_name => "any:old")
+    task = stub(:fully_qualified_name => "any:old:thing", :name => "thing", :namespace => ns)
+    after_task = stub(:fully_qualified_name => "any:old:after_thing", :name => "after_thing", :namespace => ns)
+
+    ns.stubs(:search_task).returns(nil)
+    ns.expects(:search_task).with("after_thing").returns(after_task)
+
+    @config.execute_task(task)
+    assert_equal [task, after_task], @config.called
+  end
+
+  def test_execute_task_with_on_hooks_should_trigger_hooks_around_task
+    ns = stub("namespace", :default_task => nil, :name => "old", :fully_qualified_name => "any:old")
+    task = stub(:fully_qualified_name => "any:old:thing", :name => "thing", :namespace => ns)
+    before_task = stub(:fully_qualified_name => "any:old:before_thing", :name => "before_thing", :namespace => ns)
+    after_task = stub(:fully_qualified_name => "any:old:after_thing", :name => "after_thing", :namespace => ns)
+
+    ns.stubs(:search_task).returns(nil)
+    ns.expects(:search_task).with("before_thing").returns(before_task)
+    ns.expects(:search_task).with("after_thing").returns(after_task)
+
+    @config.before("any:old:thing", :first_this, :then_this)
+    @config.after("any:old:thing", :and_then_this, :lastly_this)
+
+    [:first_this, :then_this, :and_then_this, :lastly_this].each do |t|
+      @config.expects(:find_and_execute_task).with(t)
+    end
+
+    @config.execute_task(task)
+  end
+end

data/test/configuration/connections_test.rb

@@ -0,0 +1,349 @@
+require "utils"
+require 'capistrano/configuration/connections'
+
+class ConfigurationConnectionsTest < Test::Unit::TestCase
+  class MockConfig
+    attr_reader :original_initialize_called
+    attr_reader :values
+    attr_accessor :current_task
+
+    def initialize
+      @original_initialize_called = true
+      @values = {}
+    end
+
+    def fetch(*args)
+      @values.fetch(*args)
+    end
+
+    def [](key)
+      @values[key]
+    end
+
+    def exists?(key)
+      @values.key?(key)
+    end
+
+    include Capistrano::Configuration::Connections
+  end
+
+  def setup
+    @config = MockConfig.new
+    @config.stubs(:logger).returns(stub_everything)
+    Net::SSH.stubs(:configuration_for).returns({})
+    @ssh_options = {
+      :user        => "user",
+      :port        => 8080,
+      :password    => "g00b3r",
+      :ssh_options => { :debug => :verbose }
+    }
+  end
+
+  def test_initialize_should_initialize_collections_and_call_original_initialize
+    assert @config.original_initialize_called
+    assert @config.sessions.empty?
+  end
+
+  def test_connection_factory_should_return_default_connection_factory_instance
+    factory = @config.connection_factory
+    assert_instance_of Capistrano::Configuration::Connections::DefaultConnectionFactory, factory
+  end
+
+  def test_connection_factory_instance_should_be_cached
+    assert_same @config.connection_factory, @config.connection_factory
+  end
+
+  def test_default_connection_factory_honors_config_options
+    server = server("capistrano")
+    Capistrano::SSH.expects(:connect).with(server, @config).returns(:session)
+    assert_equal :session, @config.connection_factory.connect_to(server)
+  end
+
+  def test_should_connect_through_gateway_if_gateway_variable_is_set
+    @config.values[:gateway] = "j@gateway"
+    Net::SSH::Gateway.expects(:new).with("gateway", "j", :password => nil, :auth_methods => %w(publickey hostbased), :config => false).returns(stub_everything)
+    assert_instance_of Capistrano::Configuration::Connections::GatewayConnectionFactory, @config.connection_factory
+  end
+
+  def test_connection_factory_as_gateway_should_honor_config_options
+    @config.values[:gateway] = "gateway"
+    @config.values.update(@ssh_options)
+    Net::SSH::Gateway.expects(:new).with("gateway", "user", :debug => :verbose, :port => 8080, :password => nil, :auth_methods => %w(publickey hostbased), :config => false).returns(stub_everything)
+    assert_instance_of Capistrano::Configuration::Connections::GatewayConnectionFactory, @config.connection_factory
+  end
+  
+  def test_connection_factory_as_gateway_should_chain_gateways_if_gateway_variable_is_an_array
+    @config.values[:gateway] = ["j@gateway1", "k@gateway2"]
+    gateway1 = mock
+    Net::SSH::Gateway.expects(:new).with("gateway1", "j", :password => nil, :auth_methods => %w(publickey hostbased), :config => false).returns(gateway1)
+    gateway1.expects(:open).returns(65535)
+    Net::SSH::Gateway.expects(:new).with("127.0.0.1", "k", :port => 65535, :password => nil, :auth_methods => %w(publickey hostbased), :config => false).returns(stub_everything)
+    assert_instance_of Capistrano::Configuration::Connections::GatewayConnectionFactory, @config.connection_factory
+  end
+  
+  def test_connection_factory_as_gateway_should_share_gateway_between_connections
+    @config.values[:gateway] = "j@gateway"
+    Net::SSH::Gateway.expects(:new).once.with("gateway", "j", :password => nil, :auth_methods => %w(publickey hostbased), :config => false).returns(stub_everything)
+    Capistrano::SSH.stubs(:connect).returns(stub_everything)
+    assert_instance_of Capistrano::Configuration::Connections::GatewayConnectionFactory, @config.connection_factory
+    @config.establish_connections_to(server("capistrano"))
+    @config.establish_connections_to(server("another"))
+  end
+
+  def test_establish_connections_to_should_accept_a_single_nonarray_parameter
+    Capistrano::SSH.expects(:connect).with { |s,| s.host == "capistrano" }.returns(:success)
+    assert @config.sessions.empty?
+    @config.establish_connections_to(server("capistrano"))
+    assert ["capistrano"], @config.sessions.keys
+  end
+
+  def test_establish_connections_to_should_accept_an_array
+    Capistrano::SSH.expects(:connect).times(3).returns(:success)
+    assert @config.sessions.empty?
+    @config.establish_connections_to(%w(cap1 cap2 cap3).map { |s| server(s) })
+    assert %w(cap1 cap2 cap3), @config.sessions.keys.sort
+  end
+
+  def test_establish_connections_to_should_not_attempt_to_reestablish_existing_connections
+    Capistrano::SSH.expects(:connect).times(2).returns(:success)
+    @config.sessions[server("cap1")] = :ok
+    @config.establish_connections_to(%w(cap1 cap2 cap3).map { |s| server(s) })
+    assert %w(cap1 cap2 cap3), @config.sessions.keys.sort.map { |s| s.host }
+  end
+  
+  def test_establish_connections_to_should_raise_one_connection_error_on_failure
+    Capistrano::SSH.expects(:connect).times(2).raises(Exception)
+    assert_raises(Capistrano::ConnectionError) {
+      @config.establish_connections_to(%w(cap1 cap2).map { |s| server(s) })
+    }
+  end
+
+  def test_connection_error_should_include_accessor_with_host_array
+    Capistrano::SSH.expects(:connect).times(2).raises(Exception)
+
+    begin
+      @config.establish_connections_to(%w(cap1 cap2).map { |s| server(s) })
+      flunk "expected an exception to be raised"
+    rescue Capistrano::ConnectionError => e
+      assert e.respond_to?(:hosts)
+      assert_equal %w(cap1 cap2), e.hosts.map { |h| h.to_s }.sort
+    end
+  end
+  
+  def test_connection_error_should_only_include_failed_hosts
+    Capistrano::SSH.expects(:connect).with(server('cap1'), anything).raises(Exception)
+    Capistrano::SSH.expects(:connect).with(server('cap2'), anything).returns(:success)
+
+    begin
+      @config.establish_connections_to(%w(cap1 cap2).map { |s| server(s) })
+      flunk "expected an exception to be raised"
+    rescue Capistrano::ConnectionError => e
+      assert_equal %w(cap1), e.hosts.map { |h| h.to_s }
+    end
+  end
+
+  def test_execute_on_servers_should_require_a_block
+    assert_raises(ArgumentError) { @config.execute_on_servers }
+  end
+
+  def test_execute_on_servers_without_current_task_should_call_find_servers
+    list = [server("first"), server("second")]
+    @config.expects(:find_servers).with(:a => :b, :c => :d).returns(list)
+    @config.expects(:establish_connections_to).with(list).returns(:done)
+    @config.execute_on_servers(:a => :b, :c => :d) do |result|
+      assert_equal list, result
+    end
+  end
+
+  def test_execute_on_servers_without_current_task_should_raise_error_if_no_matching_servers
+    @config.expects(:find_servers).with(:a => :b, :c => :d).returns([])
+    assert_raises(Capistrano::NoMatchingServersError) { @config.execute_on_servers(:a => :b, :c => :d) { |list| } }
+  end
+
+  def test_execute_on_servers_should_raise_an_error_if_the_current_task_has_no_matching_servers_by_default
+    @config.current_task = mock_task
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([])
+    assert_raises(Capistrano::NoMatchingServersError) do
+      @config.execute_on_servers do
+        flunk "should not get here"
+      end
+    end
+  end
+  
+  def test_execute_on_servers_should_determine_server_list_from_active_task
+    assert @config.sessions.empty?
+    @config.current_task = mock_task
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([server("cap1"), server("cap2"), server("cap3")])
+    Capistrano::SSH.expects(:connect).times(3).returns(:success)
+    @config.execute_on_servers {}
+    assert_equal %w(cap1 cap2 cap3), @config.sessions.keys.sort.map { |s| s.host }
+  end
+
+  def test_execute_on_servers_should_yield_server_list_to_block
+    assert @config.sessions.empty?
+    @config.current_task = mock_task
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([server("cap1"), server("cap2"), server("cap3")])
+    Capistrano::SSH.expects(:connect).times(3).returns(:success)
+    block_called = false
+    @config.execute_on_servers do |servers|
+      block_called = true
+      assert servers.detect { |s| s.host == "cap1" }
+      assert servers.detect { |s| s.host == "cap2" }
+      assert servers.detect { |s| s.host == "cap3" }
+      assert servers.all? { |s| @config.sessions[s] }
+    end
+    assert block_called
+  end
+
+  def test_execute_on_servers_with_once_option_should_establish_connection_to_and_yield_only_the_first_server
+    assert @config.sessions.empty?
+    @config.current_task = mock_task
+    @config.expects(:find_servers_for_task).with(@config.current_task, :once => true).returns([server("cap1"), server("cap2"), server("cap3")])
+    Capistrano::SSH.expects(:connect).returns(:success)
+    block_called = false
+    @config.execute_on_servers(:once => true) do |servers|
+      block_called = true
+      assert_equal %w(cap1), servers.map { |s| s.host }
+    end
+    assert block_called
+    assert_equal %w(cap1), @config.sessions.keys.sort.map { |s| s.host }
+  end
+  
+  def test_execute_servers_should_raise_connection_error_on_failure_by_default
+    @config.current_task = mock_task
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([server("cap1")])
+    Capistrano::SSH.expects(:connect).raises(Exception)
+    assert_raises(Capistrano::ConnectionError) do
+      @config.execute_on_servers do
+        flunk "expected an exception to be raised"
+      end
+    end
+  end
+  
+  def test_execute_servers_should_not_raise_connection_error_on_failure_with_on_errors_continue
+    @config.current_task = mock_task(:on_error => :continue)
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([server("cap1"), server("cap2")])
+    Capistrano::SSH.expects(:connect).with(server('cap1'), anything).raises(Exception)
+    Capistrano::SSH.expects(:connect).with(server('cap2'), anything).returns(:success)
+    assert_nothing_raised {
+      @config.execute_on_servers do |servers|
+        assert_equal %w(cap2), servers.map { |s| s.host }
+      end
+    }
+  end
+  
+  def test_execute_on_servers_should_not_try_to_connect_to_hosts_with_connection_errors_with_on_errors_continue
+    list = [server("cap1"), server("cap2")]
+    @config.current_task = mock_task(:on_error => :continue)
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns(list)
+    Capistrano::SSH.expects(:connect).with(server('cap1'), anything).raises(Exception)
+    Capistrano::SSH.expects(:connect).with(server('cap2'), anything).returns(:success)
+    @config.execute_on_servers do |servers|
+      assert_equal %w(cap2), servers.map { |s| s.host }
+    end
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns(list)
+    @config.execute_on_servers do |servers|
+      assert_equal %w(cap2), servers.map { |s| s.host }
+    end
+  end
+  
+  def test_execute_on_servers_should_not_try_to_connect_to_hosts_with_command_errors_with_on_errors_continue
+    cap1 = server("cap1")
+    cap2 = server("cap2")
+    @config.current_task = mock_task(:on_error => :continue)
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([cap1, cap2])
+    Capistrano::SSH.expects(:connect).times(2).returns(:success)
+    @config.execute_on_servers do |servers|
+      error = Capistrano::CommandError.new
+      error.hosts = [cap1]
+      raise error
+    end
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([cap1, cap2])
+    @config.execute_on_servers do |servers|
+      assert_equal %w(cap2), servers.map { |s| s.host }
+    end
+  end
+  
+  def test_execute_on_servers_should_not_try_to_connect_to_hosts_with_transfer_errors_with_on_errors_continue
+    cap1 = server("cap1")
+    cap2 = server("cap2")
+    @config.current_task = mock_task(:on_error => :continue)
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([cap1, cap2])
+    Capistrano::SSH.expects(:connect).times(2).returns(:success)
+    @config.execute_on_servers do |servers|
+      error = Capistrano::TransferError.new
+      error.hosts = [cap1]
+      raise error
+    end
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([cap1, cap2])
+    @config.execute_on_servers do |servers|
+      assert_equal %w(cap2), servers.map { |s| s.host }
+    end
+  end
+  
+  def test_connect_should_establish_connections_to_all_servers_in_scope
+    assert @config.sessions.empty?
+    @config.current_task = mock_task
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([server("cap1"), server("cap2"), server("cap3")])
+    Capistrano::SSH.expects(:connect).times(3).returns(:success)
+    @config.connect!
+    assert_equal %w(cap1 cap2 cap3), @config.sessions.keys.sort.map { |s| s.host }
+  end
+  
+  def test_execute_on_servers_should_only_run_on_tasks_max_hosts_hosts_at_once
+    cap1 = server("cap1")
+    cap2 = server("cap2")
+    connection1 = mock()
+    connection2 = mock()
+    connection1.expects(:close)
+    connection2.expects(:close)
+    @config.current_task = mock_task(:max_hosts => 1)
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([cap1, cap2])
+    Capistrano::SSH.expects(:connect).times(2).returns(connection1).then.returns(connection2)
+    block_called = 0
+    @config.execute_on_servers do |servers|
+      block_called += 1
+      assert_equal 1, servers.size
+    end
+    assert_equal 2, block_called
+  end
+  
+  def test_execute_on_servers_should_only_run_on_max_hosts_hosts_at_once
+    cap1 = server("cap1")
+    cap2 = server("cap2")
+    connection1 = mock()
+    connection2 = mock()
+    connection1.expects(:close)
+    connection2.expects(:close)
+    @config.current_task = mock_task(:max_hosts => 1)
+    @config.expects(:find_servers_for_task).with(@config.current_task, {}).returns([cap1, cap2])
+    Capistrano::SSH.expects(:connect).times(2).returns(connection1).then.returns(connection2)
+    block_called = 0
+    @config.execute_on_servers do |servers|
+      block_called += 1
+      assert_equal 1, servers.size
+    end
+    assert_equal 2, block_called
+  end
+  
+  def test_connect_should_honor_once_option
+    assert @config.sessions.empty?
+    @config.current_task = mock_task
+    @config.expects(:find_servers_for_task).with(@config.current_task, :once => true).returns([server("cap1"), server("cap2"), server("cap3")])
+    Capistrano::SSH.expects(:connect).returns(:success)
+    @config.connect! :once => true
+    assert_equal %w(cap1), @config.sessions.keys.sort.map { |s| s.host }
+  end
+
+  private
+
+    def mock_task(options={})
+      continue_on_error = options[:on_error] == :continue
+      stub("task",
+        :fully_qualified_name => "name",
+        :options => options,
+        :continue_on_error? => continue_on_error,
+        :max_hosts => options[:max_hosts]
+      )
+    end
+end