Clarify output configuration option

CHANGELOG.md

@@ -7,6 +7,8 @@ appear at the top.
 
   * Add your entries below here, remember to credit yourself however you want
     to be credited!
+  * Removed broken support for assigning an `IO` to the `output` config option (See [#243](https://github.com/capistrano/sshkit/issues/243)). @robd
+    * Use `SSHKit.config.output = SSHKit::Formatter::SimpleText.new($stdin)` instead
   * Added support for :interaction_handler option on commands. @robd
   * Removed partially supported 'trace' log level. @robd
   * No longer strip whitespace or newlines in `capture` method on Netssh backend. @robd

EXAMPLES.md

@@ -206,23 +206,41 @@ on hosts do
 end
 ```
 
-## Redirect all output to `/dev/null`
+## Change the output formatter
 
 ```ruby
-SSHKit.config.output = File.open('/dev/null')
+# The default format is pretty, which outputs colored text
+SSHKit.config.format = :pretty
+
+# Text with no coloring
+SSHKit.config.format = :simpletext
+
+# Red / Green dots for each completed step
+SSHKit.config.format = :dot
+
+# No output
+SSHKit.config.format = :blackhole
 ```
 
 ## Implement a dirt-simple formatter class
 
 ```ruby
-class MyFormatter < SSHKit::Formatter::Abstract
-  def write(obj)
-    case obj.is_a? SSHKit::Command
-      # Do something here, see the SSHKit::Command documentation
+module SSHKit
+  module Formatter
+    class MyFormatter < SSHKit::Formatter::Abstract
+      def write(obj)
+        case obj.is_a? SSHKit::Command
+          # Do something here, see the SSHKit::Command documentation
+        end
+      end
     end
   end
 end
 
+# If your formatter is defined in the SSHKit::Formatter module configure with the format option:
+SSHKit.config.format = :myformatter
+
+# Or configure the output directly
 SSHKit.config.output = MyFormatter.new($stdout)
 SSHKit.config.output = MyFormatter.new(SSHKit.config.output)
 SSHKit.config.output = MyFormatter.new(File.open('log/deploy.log', 'wb'))

README.md

@@ -355,23 +355,32 @@ By default, the output format is set to `:pretty`:
 SSHKit.config.format = :pretty
 ```
 
-However, if you prefer minimal output, `:dot` format will simply output red or green dots based on the success or failure of operations.
+However, if you prefer non colored text you can use the `:simpletext` formatter. If you want minimal output,
+there is also a `:dot` formatter which will simply output red or green dots based on the success or failure of commands.
+There is also a `:blackhole` formatter which does not output anything.
 
-To output directly to $stdout without any formatting, you can use:
+By default, formatters log to `$stdout`, but they can be constructed with any `IO`:
 
 ```ruby
-SSHKit.config.output = $stdout
+# Output to a StringIO:
+out = StringIO.new
+SSHKit.config.output = SSHKit::Formatter::Pretty.new(out)
+# Do something with out.string
+
+# Or output to a file:
+SSHKit.config.output = SSHKit::Formatter::SimpleText.new(File.open('log/deploy.log', 'wb'))
 ```
 
 #### Custom formatters
 
 Want custom output formatting? Here's what you have to do:
 
-1. Write a new formatter class in the `SSHKit::Formatter` namespace. As an example, check out the default [pretty](https://github.com/capistrano/sshkit/blob/master/lib/sshkit/formatters/pretty.rb) formatter.
-1. Set the output format as described above. E.g. if your new formatter is called `Foobar`:
-
-        SSHKit.config.format = :foobar
+1. Write a new formatter class in the `SSHKit::Formatter` module. As an example, check out the default [pretty](https://github.com/capistrano/sshkit/blob/master/lib/sshkit/formatters/pretty.rb) formatter.
+1. Set the output format as described above. E.g. if your new formatter is called `FooBar`:
 
+```ruby
+SSHKit.config.format = :foobar
+```
 
 ## Output Verbosity
 

lib/sshkit.rb

@@ -6,15 +6,6 @@ class << self
 
     attr_accessor :config
 
-    def capture_output(io, &block)
-      original_io = config.output
-      config.output = io
-      config.output.extend(SSHKit::Utils::CaptureOutputMethods)
-      yield
-    ensure
-      config.output = original_io
-    end
-
     def configure
       @@config ||= Configuration.new
       yield config

lib/sshkit/all.rb

@@ -33,6 +33,4 @@
 require_relative 'backends/printer'
 require_relative 'backends/netssh'
 require_relative 'backends/local'
-require_relative 'backends/skipper'
-
-require_relative 'utils/capture_output_methods'
+require_relative 'backends/skipper'

test/functional/backends/test_netssh.rb

@@ -10,54 +10,45 @@ class TestNetssh < FunctionalTest
 
       def setup
         super
-        SSHKit.config.output = SSHKit::Formatter::BlackHole.new($stdout)
-      end
-
-      def block_to_run
-        lambda do |host|
-          execute 'date'
-          execute :ls, '-l', '/some/directory'
-          with rails_env: :production do
-            within '/tmp' do
-              as :root do
-                execute :touch, 'restart.txt'
-              end
-            end
-          end
-        end
+        @out = StringIO.new
+        SSHKit.config.output_verbosity = :debug
+        SSHKit.config.output = SSHKit::Formatter::SimpleText.new(@out)
       end
 
       def a_host
         VagrantWrapper.hosts['one']
       end
 
-      def simple_netssh
-        SSHKit.capture_output(sio) do
-          Netssh.new(a_host, &block_to_run).run
-        end
-        sio.rewind
-        result = sio.read
-        assert_equal <<-EOEXPECTED.unindent, result
-          if test ! -d /opt/sites/example.com; then echo "Directory does not exist '/opt/sites/example.com'" 2>&1; false; fi
-          cd /opt/sites/example.com && /usr/bin/env date
-          cd /opt/sites/example.com && /usr/bin/env ls -l /some/directory
-          if test ! -d /opt/sites/example.com/tmp; then echo "Directory does not exist '/opt/sites/example.com/tmp'" 2>&1; false; fi
-          if ! sudo su -u root whoami > /dev/null; then echo "You cannot switch to user 'root' using sudo, please check the sudoers file" 2>&1; false; fi
-          cd /opt/sites/example.com/tmp && ( RAILS_ENV=production ( sudo su -u root /usr/bin/env touch restart.txt ) )
+      def test_simple_netssh
+        Netssh.new(a_host) do
+          execute 'date'
+          execute :ls, '-l'
+          with rails_env: :production do
+           within '/tmp' do
+             as :root do
+               execute :touch, 'restart.txt'
+             end
+           end
+          end
+        end.run
+
+        command_lines = @out.string.lines.select { |line| line.start_with?('Command:') }
+        assert_equal <<-EOEXPECTED.unindent, command_lines.join
+          Command: /usr/bin/env date
+          Command: /usr/bin/env ls -l
+          Command: if test ! -d /tmp; then echo \"Directory does not exist '/tmp'\" 1>&2; false; fi
+          Command: if ! sudo -u root whoami > /dev/null; then echo \"You cannot switch to user 'root' using sudo, please check the sudoers file\" 1>&2; false; fi
+          Command: cd /tmp && ( RAILS_ENV=production sudo -u root RAILS_ENV=production -- sh -c '/usr/bin/env touch restart.txt' )
         EOEXPECTED
       end
 
       def test_capture
-        File.open('/dev/null', 'w') do |dnull|
-          SSHKit.capture_output(dnull) do
-            captured_command_result = nil
-            Netssh.new(a_host) do |host|
-              captured_command_result = capture(:uname)
-            end.run
-
-            assert_includes %W(Linux\n Darwin\n), captured_command_result
-          end
-        end
+        captured_command_result = nil
+        Netssh.new(a_host) do |host|
+          captured_command_result = capture(:uname)
+        end.run
+
+        assert_includes %W(Linux\n Darwin\n), captured_command_result
       end
 
       def test_ssh_option_merge

test/unit/formatters/test_dot.rb

@@ -5,6 +5,7 @@ module SSHKit
   class TestDot < UnitTest
 
     def setup
+      super
       SSHKit.config.output_verbosity = Logger::DEBUG
     end
 

test/unit/formatters/test_pretty.rb

@@ -5,6 +5,7 @@ module SSHKit
   class TestPretty < UnitTest
 
     def setup
+      super
       SSHKit.config.output_verbosity = Logger::DEBUG
     end
 

test/unit/formatters/test_simple_text.rb

@@ -5,6 +5,7 @@ module SSHKit
   class TestSimpleText < UnitTest
 
     def setup
+      super
       SSHKit.config.output_verbosity = Logger::DEBUG
     end
 

test/unit/test_command.rb

@@ -4,10 +4,6 @@
 module SSHKit
   class TestCommand < UnitTest
 
-    def setup
-      SSHKit.reset_configuration!
-    end
-
     def test_maps_a_command
       c = Command.new('example')
       assert_equal '/usr/bin/env example', c.to_command

test/unit/test_command_map.rb

@@ -4,10 +4,6 @@
 module SSHKit
   class TestCommandMap < UnitTest
 
-    def setup
-      SSHKit.reset_configuration!
-    end
-
     def test_defaults
       map = CommandMap.new
       assert_equal map[:rake], "/usr/bin/env rake"

test/unit/test_configuration.rb

@@ -5,7 +5,7 @@ module SSHKit
   class TestConfiguration < UnitTest
 
     def setup
-      SSHKit.config = nil
+      super
       SSHKit.config.command_map.clear
       SSHKit.config.output = SSHKit::Formatter::Pretty.new($stdout)
     end
@@ -51,15 +51,17 @@ def test_command_map
       assert_equal "/opt/sites/example/current/bin ruby", SSHKit.config.command_map[:ruby]
     end
 
-    def test_setting_formatter_to_dot
-      assert SSHKit.config.format = :dot
-      assert SSHKit.config.output.is_a? SSHKit::Formatter::Dot
+    def test_setting_formatter_types
+      {
+        dot:        SSHKit::Formatter::Dot,
+        blackhole:  SSHKit::Formatter::BlackHole,
+        simpletext: SSHKit::Formatter::SimpleText,
+      }.each do |format, expected_class|
+        SSHKit.config.format = format
+        assert SSHKit.config.output.is_a? expected_class
+      end
     end
 
-    def test_setting_formatter_to_blackhole
-      assert SSHKit.config.format = :BlackHole
-      assert SSHKit.config.output.is_a? SSHKit::Formatter::BlackHole
-    end
   end
 
 end