process_helper 0.0.1

data/process_helper.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'process_helper/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'process_helper'
+  spec.version = ProcessHelper::VERSION
+  spec.authors = ['Glenn Oppegard', 'Chad Woolley']
+  spec.email = ['oppegard@gmail.com', 'thewoolleyman@gmail.com']
+  spec.summary = "Makes it easier to spawn ruby sub-processes with proper capturing /
+    of stdout and stderr streams."
+  spec.description = 'Wrapper around Open3#popen2e with other useful options.'
+  spec.homepage = 'https://github.com/thewoolleyman/process_helper'
+  spec.license = 'Unlicense'
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.executables = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 1.9.2'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+  spec.add_development_dependency 'rake', '~> 10'
+  spec.add_development_dependency 'rspec', '~> 3.1'
+  spec.add_development_dependency 'rubocop', '= 0.29.1' # exact version for static analyis libs
+  spec.add_development_dependency 'ruby-lint', '= 2.0.2' # exact version for static analyis libs
+end

data/ruby-lint.yml

@@ -0,0 +1,12 @@
+---
+# http://code.yorickpeterse.com/ruby-lint/latest/
+analysis_classes:
+ - argument_amount
+ - pedantics
+ - shadowing_variables
+# - undefined_methods
+# - undefined_variables
+ - unused_variables
+ - useless_equality_checks
+directories:
+ - spec

data/spec/error_handling_spec.rb

@@ -0,0 +1,21 @@
+require_relative 'spec_helper'
+
+RSpec.describe 'error handling' do
+  attr_reader :clazz
+
+  before do
+    @clazz = Clazz.new
+  end
+
+  it 'fails if command is nil' do
+    expect { clazz.process(nil) }.to raise_error(
+        ProcessHelper::EmptyCommandError,
+        'command must not be empty')
+  end
+
+  it 'fails if command is empty' do
+    expect { clazz.process('') }.to raise_error(
+        ProcessHelper::EmptyCommandError,
+        'command must not be empty')
+  end
+end

data/spec/input_handling_spec.rb

@@ -0,0 +1,125 @@
+require_relative 'spec_helper'
+
+RSpec.describe 'input handling' do
+  attr_reader :clazz, :max_process_wait
+
+  before do
+    @clazz = Clazz.new
+    @max_process_wait = ENV['MAX_PROCESS_WAIT'] ? ENV['MAX_PROCESS_WAIT'].to_f : 0.5
+  end
+
+  describe 'with non-exiting blocking cmd requiring timeout' do
+    it 'handles a single line of STDIN to STDOUT with ruby output flushing' do
+      expect do
+        clazz.process(
+          "ruby -e 'while(i=$stdin.gets) do puts i; $stdout.flush; end'",
+          input_lines: ['input1'],
+          timeout: max_process_wait
+        )
+      end.to output(/input1\n/).to_stdout
+          .and(not_output.to_stderr)
+    end
+
+    it 'handles multiple lines of STDIN to STDOUT with ruby output flushing' do
+      expect do
+        clazz.process(
+          "ruby -e 'while(i=$stdin.gets) do puts i; $stdout.flush; end'",
+          input_lines: %w(input1 input2),
+          timeout: max_process_wait
+        )
+      end.to output(/input1\ninput2\n/).to_stdout
+          .and(not_output.to_stderr)
+    end
+
+    it 'handles cat cmd' do
+      expect do
+        clazz.process(
+          # -u disables output buffering, -n numbers output lines (to distinguish from input)
+          'cat -u -n',
+          # TODO: how to send Ctrl-D to exit without timeout being required?
+          input_lines: ['line1', 'line2', 'line3', "\C-d"],
+          timeout: max_process_wait
+        )
+      end.to output(/.*1\tline1\n.*2\tline2\n.*3\tline3\n.*4\t\u0004\n/).to_stdout
+          .and(not_output.to_stderr)
+    end
+
+    it 'handles interleaved stdout and stderr based on stdin input' do
+      expect do
+        cmd =
+          'while ' \
+          '  line = $stdin.readline; ' \
+          '  $stdout.puts("out:#{line}"); ' \
+          '  $stdout.flush; ' \
+          '  $stderr.puts("err:#{line}"); ' \
+          '  $stderr.flush; ' \
+          '  exit 0 if line =~ /exit/; ' \
+          'end'
+        clazz.process(
+          %(ruby -e '#{cmd}'),
+          input_lines: %w(line1 line2 line3 exit),
+          timeout: max_process_wait
+        )
+      end.to output(/out:line1\nerr:line1\nout:line2\nerr:line2\nout:line3\nerr:line3\n/).to_stdout
+          .and(not_output.to_stderr)
+    end
+  end
+
+  describe 'with exiting cmd' do
+    it 'handles stdout and stderr triggered via stdin' do
+      expect do
+        clazz.process(
+          'irb -f --prompt=default',
+          input_lines: [
+            '$stdout.puts "hi"',
+            '$stdout.flush',
+            '$stderr.puts "aaa\nbbb\nccc"',
+            '$stderr.flush',
+            '$stdout.puts "bye"',
+            '$stdout.flush',
+            'exit'
+          ]
+        )
+      end.to output(/\nhi\n.*\naaa\nbbb\nccc.*\nbye\n/m).to_stdout
+          .and(not_output.to_stderr)
+    end
+
+    it 'handles unexpected exit status' do
+      expect do
+        clazz.process(
+          "ruby -e 'i=$stdin.gets; $stdout.puts i; $stdout.flush; " \
+          "$stderr.puts i; $stderr.flush; exit 1'",
+          puts_output: :error,
+          input_lines: ['hi']
+        )
+      end.to raise_error(
+          ProcessHelper::UnexpectedExitStatusError,
+          /Command failed/)
+          .and(output(/hi\nhi\n/).to_stdout)
+    end
+
+    it 'pipes input before processing output' do
+      expect do
+        clazz.process(
+          "ruby -e 'i=$stdin.gets; $stdout.puts i; $stdout.flush; exit'",
+          input_lines: ['hi']
+        )
+      end.to output(/hi\n/m).to_stdout
+          .and(not_output.to_stderr)
+    end
+
+    it 'fails if unprocessed input remains when command exits' do
+      # TODO: This fails when run with code coverage instrumentation
+      #       enabled (via RubyMine).  Why???
+      expect do
+        clazz.process(
+          "ruby -e 'i=$stdin.gets; $stdout.puts i; exit'",
+          input_lines: %w(hi unprocessed)
+        )
+      end.to raise_error(
+          ProcessHelper::UnprocessedInputError,
+          /Output stream closed with 1 input lines left unprocessed/)
+          .and(output(/hi\n/).to_stdout)
+    end
+  end
+end

data/spec/options/expected_exit_status_spec.rb

@@ -0,0 +1,138 @@
+require_relative '../spec_helper'
+
+RSpec.describe ':expected_exit_status option' do
+  attr_reader :clazz
+
+  before do
+    @clazz = Clazz.new
+  end
+
+  describe '== 0 (default)' do
+    describe 'when exit_status == 0' do
+      it 'succeeds' do
+        expect do
+          clazz.process('echo')
+        end.to not_raise_error
+            .and(output("\n").to_stdout)
+      end
+
+      it 'succeeds when :expected_exit_status is explicitly 0' do
+        expect do
+          clazz.process('echo', exp_st: 0)
+        end.to not_raise_error
+            .and(output("\n").to_stdout)
+      end
+    end
+
+    describe 'when exit_status != 0' do
+      it 'fails with message' do
+        cmd_regex = Regexp.escape('`ls /does_not_exist`')
+        expect do
+          clazz.process('ls /does_not_exist', puts_output: :error)
+        end.to raise_error(
+            ProcessHelper::UnexpectedExitStatusError,
+            /Command failed, pid \d+ exit [1,2]\. Command: #{cmd_regex}\./
+          )
+            .and(output(/No such file or directory/).to_stdout)
+      end
+    end
+  end
+
+  describe '!= 0' do
+    describe 'when exit_status == 0' do
+      it 'fails with message' do
+        expected_regex = 'Command succeeded but was expected to fail, ' \
+          'pid \d+ exit 0 \(expected \[1, 2\]\). Command: ' \
+          "#{Regexp.escape('`echo`')}" \
+          '\.'
+        expect do
+          clazz.process('echo', exp_st: [1, 2], puts_output: :error)
+        end.to raise_error(ProcessHelper::UnexpectedExitStatusError, /#{expected_regex}/)
+            .and(output("\n").to_stdout)
+      end
+    end
+
+    describe 'when exit_status != 0' do
+      it 'succeeds' do
+        expect do
+          clazz.process('ls /does_not_exist', exp_st: [1, 2], puts_output: :error)
+        end.to_not raise_error
+      end
+    end
+  end
+
+  describe 'multiple values' do
+    describe 'when exit_status == 0' do
+      describe 'when 0 is one of the expected values' do
+        it 'succeeds' do
+          expect do
+            clazz.process(
+              'echo',
+              expected_exit_status: [0, 98, 99],
+            )
+          end.to not_raise_error
+              .and(output("\n").to_stdout)
+        end
+      end
+
+      describe 'when 0 is not one of the expected values' do
+        it 'fails with message' do
+          expected_regex = 'Command succeeded but was expected to fail, ' \
+            'pid \d+ exit 0 \(expected \[98, 99\]\). Command: ' \
+            "#{Regexp.escape('`echo`')}" \
+            '\.'
+          expect do
+            clazz.process(
+              'echo',
+              expected_exit_status: [98, 99],
+            )
+          end.to raise_error(
+              ProcessHelper::UnexpectedExitStatusError,
+              /#{expected_regex}/
+            )
+              .and(output("\n").to_stdout)
+        end
+      end
+    end
+
+    describe 'when exit_status != 0' do
+      describe 'when the exit status is one of the expected values' do
+        it 'succeeds' do
+          expect do
+            clazz.process(
+              'ls /does_not_exist',
+              expected_exit_status: [0, 1, 2],
+            )
+          end.to not_raise_error
+              .and(output(/No such file or directory/).to_stdout)
+        end
+      end
+
+      describe 'when the exit status is not one of the expected values' do
+        it 'fails with message' do
+          expected_regex = 'Command did not exit with one of the expected exit statuses, ' \
+            'pid \d+ exit [1,2] \(expected \[0, 98, 99\]\). Command: ' \
+            "#{Regexp.escape('`ls /does_not_exist`')}" \
+            '\.'
+          expect do
+            clazz.process(
+              'ls /does_not_exist',
+              expected_exit_status: [0, 98, 99],
+              puts_output: :error)
+          end.to raise_error(
+              ProcessHelper::UnexpectedExitStatusError,
+              /#{expected_regex}/
+            )
+              .and(output(/No such file or directory/).to_stdout)
+        end
+      end
+    end
+  end
+
+  it 'supports long form of option' do
+    expect do
+      clazz.process('echo', expected_exit_status: 0)
+    end.to not_raise_error
+        .and(output("\n").to_stdout)
+  end
+end

data/spec/options/include_output_in_exception_spec.rb

@@ -0,0 +1,75 @@
+require_relative '../spec_helper'
+
+RSpec.describe ':include_output_in_exception option' do
+  attr_reader :clazz
+
+  before do
+    @clazz = Clazz.new
+  end
+
+  describe '== true (default)' do
+    describe 'includes output in exception if exception' do
+      it 'when :expected_exit_status is zero' do
+        expect do
+          clazz.process(
+            'ls /does_not_exist',
+            puts_output: :error,
+            include_output_in_exception: true
+          )
+        end.to raise_error(
+            ProcessHelper::UnexpectedExitStatusError,
+            /Command Output: "ls:.*\/does_not_exist: No such file or directory\n"/)
+            .and(output(/No such file or directory/).to_stdout)
+      end
+
+      it 'when :expected_exit_status is nonzero' do
+        expect do
+          clazz.process(
+            'echo stdout > /dev/stdout',
+            puts_output: :error,
+            expected_exit_status: 1,
+            include_output_in_exception: true)
+        end.to raise_error(
+            ProcessHelper::UnexpectedExitStatusError,
+            /Command Output: "stdout\n"/)
+            .and(output("stdout\n").to_stdout)
+      end
+    end
+  end
+
+  describe '== false' do
+    describe 'does not includes output in exception if exception' do
+      it 'when :expected_exit_status is zero' do
+        expect do
+          clazz.process(
+            'ls /does_not_exist',
+            puts_output: :error,
+            include_output_in_exception: false)
+        end
+          .to output(/No such file or directory/).to_stdout
+              .and(
+                raise_error(ProcessHelper::UnexpectedExitStatusError) do |e|
+                  expect(e.message).not_to match(/Command Output/)
+                  expect(e.message).not_to match(/No such file or directory/)
+                end
+              )
+      end
+
+      it 'when :expected_exit_status is nonzero' do
+        expect do
+          clazz.process(
+            'echo stdout > /dev/stdout',
+            expected_exit_status: 1,
+            puts_output: :error,
+            include_output_in_exception: false)
+        end.to output("stdout\n").to_stdout
+            .and(
+              raise_error(ProcessHelper::UnexpectedExitStatusError) do |e|
+                expect(e.message).not_to match(/Command Output:/)
+                expect(e.message).not_to match(/No such file or directory/)
+              end
+            )
+      end
+    end
+  end
+end

data/spec/options/puts_output_spec.rb

@@ -0,0 +1,76 @@
+require_relative '../spec_helper'
+
+RSpec.describe ':puts_output option' do
+  attr_reader :clazz
+
+  before do
+    @clazz = Clazz.new
+  end
+
+  describe '== :always (default)' do
+    it 'puts output to stdout' do
+      expect do
+        clazz.process('echo stdout > /dev/stdout', puts_output: :always)
+      end.to output("stdout\n").to_stdout
+
+      expect do
+        clazz.process('echo stdout > /dev/stdout')
+      end.to output("stdout\n").to_stdout
+    end
+  end
+
+  describe '== :error' do
+    describe 'when :expected_exit_status is zero' do
+      it 'puts output to stdout on exception' do
+        expect do
+          clazz.process('ls /does_not_exist', puts_output: :error)
+        end.to raise_error(
+            ProcessHelper::UnexpectedExitStatusError,
+            /Command failed/)
+            .and(output(/No such file or directory/).to_stdout)
+      end
+
+      it 'suppresses stdout if no exception' do
+        expect do
+          clazz.process('echo stdout > /dev/stdout', puts_output: :error)
+        end.to not_output.to_stdout
+            .and(not_output.to_stderr)
+      end
+    end
+
+    describe 'when :expected_exit_status is nonzero' do
+      it 'puts output to stdout on exception' do
+        expect do
+          clazz.process(
+            'echo stdout > /dev/stdout',
+            expected_exit_status: 1,
+            puts_output: :error)
+        end.to raise_error(
+            ProcessHelper::UnexpectedExitStatusError,
+            /Command succeeded but was expected to fail/)
+            .and(output("stdout\n").to_stdout)
+      end
+
+      it 'suppresses stdout if no exception' do
+        expect do
+          clazz.process(
+            'ls /does_not_exist',
+            expected_exit_status: [1, 2],
+            puts_output: :error)
+        end.to not_output.to_stdout
+            .and(not_output.to_stderr)
+      end
+    end
+  end
+
+  describe '== :never' do
+    it 'suppresses stdout' do
+      expect do
+        clazz.process(
+          'echo stdout > /dev/stdout',
+          puts_output: :never)
+      end.to not_output.to_stdout
+          .and(output(/WARNING/).to_stderr)
+    end
+  end
+end