blue-shell 0.0.1

data/LICENSE

@@ -0,0 +1,14 @@
+The MIT License (MIT)
+Copyright (c) 2013 Pivotal Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/blue-shell.rb

@@ -0,0 +1,6 @@
+require 'blue-shell/errors'
+require 'blue-shell/matchers'
+require 'blue-shell/matchers/exit_code_matcher'
+require 'blue-shell/matchers/output_matcher'
+require 'blue-shell/runner'
+require 'blue-shell/buffered_reader_expector'

data/lib/blue-shell/buffered_reader_expector.rb

@@ -0,0 +1,73 @@
+module BlueShell
+  class BufferedReaderExpector
+    attr_reader :output
+
+    def initialize(out, debug = false)
+      @out = out
+      @debug = debug
+      @unused = ""
+      @output = ""
+    end
+
+    def expect(pattern, timeout = 5)
+      buffer = ''
+
+      case pattern
+        when String
+          pattern = Regexp.new(Regexp.quote(pattern))
+        when Regexp
+        else
+          raise TypeError, "unsupported pattern class: #{pattern.class}"
+      end
+
+      result = nil
+      position = 0
+      @unused ||= ""
+
+      while true
+        if !@unused.empty?
+          c = @unused.slice!(0).chr
+        elsif output_ended?(timeout)
+          @unused = buffer
+          break
+        else
+          c = @out.getc.chr
+        end
+
+        STDOUT.putc c if @debug
+
+        # wear your flip flops
+        unless (c == "\e") .. (c == "m")
+          if c == "\b"
+            if position > 0 && buffer[position - 1] && buffer[position - 1].chr != "\n"
+              position -= 1
+            end
+          else
+            if buffer.size > position
+              buffer[position] = c
+            else
+              buffer << c
+            end
+
+            position += 1
+          end
+        end
+
+        if matches = pattern.match(buffer)
+          result = [buffer, *matches.to_a[1..-1]]
+          break
+        end
+      end
+
+      @output << buffer
+
+      result
+    end
+
+    private
+
+    def output_ended?(timeout)
+      (@out.is_a?(IO) && !IO.select([@out], nil, nil, timeout)) || @out.eof?
+    end
+  end
+end

data/lib/blue-shell/errors.rb

@@ -0,0 +1,12 @@
+module BlueShell
+  module Errors
+    class InvalidInputError < StandardError; end
+
+    class NonZeroExitCodeError < StandardError
+      attr_reader :exit_code
+      def initialize(exit_code)
+        @exit_code = exit_code
+      end
+    end
+  end
+end

data/lib/blue-shell/matchers.rb

@@ -0,0 +1,13 @@
+module BlueShell
+  module Matchers
+    def say(expected_output, timeout = 30)
+      OutputMatcher.new(expected_output, timeout)
+    end
+
+    def have_exited_with(expected_code)
+      ExitCodeMatcher.new(expected_code)
+    end
+
+    alias :exit_with :have_exited_with
+  end
+end

data/lib/blue-shell/matchers/exit_code_matcher.rb

@@ -0,0 +1,40 @@
+module BlueShell
+  module Matchers
+    class ExitCodeMatcher
+      def initialize(expected_code)
+        @expected_code = expected_code
+      end
+
+      def matches?(runner)
+        raise Errors::InvalidInputError unless runner.respond_to?(:exit_code)
+
+        begin
+          Timeout.timeout(5) do
+            @actual_code = runner.exit_code
+          end
+
+          @actual_code == @expected_code
+        rescue Timeout::Error
+          @timed_out = true
+          false
+        end
+      end
+
+      def failure_message
+        if @timed_out
+          "expected process to exit with status #@expected_code, but it did not exit within 5 seconds"
+        else
+          "expected process to exit with status #{@expected_code}, but it exited with status #{@actual_code}"
+        end
+      end
+
+      def negative_failure_message
+        if @timed_out
+          "expected process to exit with status #@expected_code, but it did not exit within 5 seconds"
+        else
+          "expected process to not exit with status #{@expected_code}, but it did"
+        end
+      end
+    end
+  end
+end

data/lib/blue-shell/matchers/output_matcher.rb

@@ -0,0 +1,38 @@
+module BlueShell
+  module Matchers
+    class OutputMatcher
+      attr_reader :timeout
+
+      def initialize(expected_output, timeout = 30)
+        @expected_output = expected_output
+        @timeout = timeout
+      end
+
+      def matches?(runner)
+        raise Errors::InvalidInputError unless runner.respond_to?(:expect)
+        @matched = runner.expect(@expected_output, @timeout)
+        @full_output = runner.output
+        !!@matched
+      end
+
+      def failure_message
+        if @expected_output.is_a?(Hash)
+          expected_keys = @expected_output.keys.map{|key| "'#{key}'"}.join(', ')
+          "expected one of #{expected_keys} to be printed, but it wasn't. full output:\n#@full_output"
+        else
+          "expected '#{@expected_output}' to be printed, but it wasn't. full output:\n#@full_output"
+        end
+      end
+
+      def negative_failure_message
+        if @expected_output.is_a?(Hash)
+          match = @matched
+        else
+          match = @expected_output
+        end
+
+        "expected '#{match}' to not be printed, but it was. full output:\n#@full_output"
+      end
+    end
+  end
+end

data/lib/blue-shell/runner.rb

@@ -0,0 +1,98 @@
+require 'pty'
+require 'timeout'
+
+module BlueShell
+  class Runner
+    def initialize(*args)
+      @stdout, slave = PTY.open
+      system('stty raw', :in => slave)
+      read, @stdin = IO.pipe
+
+      @pid = spawn(*(args.push(:in => read, :out => slave, :err => slave)))
+
+      @expector = BufferedReaderExpector.new(@stdout, ENV['DEBUG_BACON'])
+
+      if block_given?
+        yield self
+      else
+        code = exit_code
+        raise Errors::NonZeroExitCodeError.new(code) unless code == 0
+      end
+    end
+
+    class << self
+      alias_method :run, :new
+    end
+
+    def expect(matcher, timeout = 30)
+      case matcher
+      when Hash
+        expect_branches(matcher, timeout)
+      else
+        @expector.expect(matcher, timeout)
+      end
+    end
+
+    def send_keys(text_to_send)
+      @stdin.puts(text_to_send)
+    end
+
+    def exit_code
+      return @code if @code
+
+      code = nil
+      Timeout.timeout(5) do
+        _, code = Process.waitpid2(@pid)
+      end
+
+      @code = numeric_exit_code(code)
+    end
+
+    alias_method :wait_for_exit, :exit_code
+
+    def exited?
+      !running?
+    end
+
+    def success?
+      @code.zero?
+    end
+
+    alias_method :successful?, :success?
+
+    def running?
+      !!Process.getpgid(@pid)
+    end
+
+    def output
+      @expector.output
+    end
+
+    def debug
+      @expector.debug
+    end
+
+    def debug=(x)
+      @expector.debug = x
+    end
+
+    private
+
+    def expect_branches(branches, timeout)
+      branch_names = /#{branches.keys.collect { |k| Regexp.quote(k) }.join('|')}/
+      expected = @expector.expect(branch_names, timeout)
+      return unless expected
+
+      data = expected.first.match(/(#{branch_names})$/)
+      matched = data[1]
+      branches[matched].call
+      matched
+    end
+
+    def numeric_exit_code(status)
+      status.exitstatus
+    rescue NoMethodError
+      status
+    end
+  end
+end

data/lib/blue-shell/version.rb

@@ -0,0 +1,3 @@
+module BlueShell
+  VERSION = "0.0.1".freeze
+end

data/spec/assets/input.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$stdout.sync = true
+print "started"
+typed = gets
+print "received #{typed}"

data/spec/assets/pause.rb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+print "started"
+sleep 0.5
+print " finished"

data/spec/matchers/exit_code_matcher_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+module BlueShell
+  module Matchers
+    describe ExitCodeMatcher, :ruby19 => true do
+      let(:expected_code) { 0 }
+
+      subject { ExitCodeMatcher.new(expected_code) }
+
+      describe "#matches?" do
+        context "with something that isn't a runner" do
+          it "raises an exception" do
+            expect {
+              subject.matches?("c'est ne pas une specker runner")
+            }.to raise_exception(Errors::InvalidInputError)
+          end
+        end
+
+        context "with a valid runner" do
+          context "and the command exited with the expected exit code" do
+            it "returns true" do
+              BlueShell::Runner.run("true") do |runner|
+                subject.matches?(runner).should be_true
+              end
+            end
+          end
+
+          context "and the command exits with a different exit code" do
+            it "returns false" do
+              BlueShell::Runner.run("false") do |runner|
+                subject.matches?(runner).should be_false
+              end
+            end
+          end
+
+          context "and the command runs for a while" do
+            it "waits for it to exit" do
+              BlueShell::Runner.run("sleep 0.5") do |runner|
+                subject.matches?(runner).should be_true
+              end
+            end
+          end
+        end
+      end
+
+      context "failure messages" do
+        context "with a command that's exited" do
+          it "has a correct failure message" do
+            BlueShell::Runner.run("false") do |runner|
+              subject.matches?(runner)
+              runner.wait_for_exit
+              subject.failure_message.should == "expected process to exit with status 0, but it exited with status 1"
+            end
+          end
+
+          it "has a correct negative failure message" do
+            BlueShell::Runner.run("false") do |runner|
+              subject.matches?(runner)
+              runner.wait_for_exit
+              subject.negative_failure_message.should == "expected process to not exit with status 0, but it did"
+            end
+          end
+        end
+
+        context "with a command that's still running" do
+          it "waits for it to exit" do
+            BlueShell::Runner.run("ruby -e 'sleep 1; exit 1'") do |runner|
+              subject.matches?(runner)
+              subject.failure_message.should == "expected process to exit with status 0, but it exited with status 1"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/matchers/output_matcher_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+
+module BlueShell
+  module Matchers
+    describe OutputMatcher, :ruby19 => true do
+      let(:expected_output) { "expected_output" }
+      let(:timeout) { 1 }
+
+      subject { OutputMatcher.new(expected_output, timeout) }
+
+      describe "#matches?" do
+        context "with something that isn't a runner" do
+          it "raises an exception" do
+            expect {
+              subject.matches?("c'est ne pas une specker runner")
+            }.to raise_exception(Errors::InvalidInputError)
+          end
+        end
+
+        context "with a valid runner" do
+          context "when the expected output is in the process output" do
+            it "finds the expected output" do
+              BlueShell::Runner.run("echo -n expected_output") do |runner|
+                subject.matches?(runner).should be_true
+              end
+            end
+          end
+
+          context "when the expected output is not in the process output" do
+            let(:runner) { Runner.new('echo -n not_what_we_were_expecting') }
+
+            it "does not find the expected output" do
+              BlueShell::Runner.run("echo -n not_what_we_were_expecting") do |runner|
+                subject.matches?(runner).should be_false
+              end
+            end
+          end
+        end
+      end
+
+      context "failure messages" do
+        it "has a correct failure message" do
+          BlueShell::Runner.run("echo -n actual_output") do |runner|
+            subject.matches?(runner)
+            subject.failure_message.should == "expected 'expected_output' to be printed, but it wasn't. full output:\nactual_output"
+          end
+        end
+
+        it "has a correct negative failure message" do
+          BlueShell::Runner.run("echo -n actual_output") do |runner|
+            subject.matches?(runner)
+            subject.negative_failure_message.should == "expected 'expected_output' to not be printed, but it was. full output:\nactual_output"
+          end
+        end
+
+        context "when expecting branching output" do
+          let(:expected_output) { {
+            "expected_output" => proc {},
+            "other_expected_output" => proc {}
+          } }
+
+          it "has a correct failure message" do
+            BlueShell::Runner.run("echo -n actual_output") do |runner|
+              subject.matches?(runner)
+              subject.failure_message.should == "expected one of 'expected_output', 'other_expected_output' to be printed, but it wasn't. full output:\nactual_output"
+            end
+          end
+
+          it "has a correct negative failure message" do
+            BlueShell::Runner.run("echo -n expected_output") do |runner|
+              subject.matches?(runner)
+              subject.negative_failure_message.should == "expected 'expected_output' to not be printed, but it was. full output:\nexpected_output"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/matchers_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+module BlueShell
+  describe Matchers do
+    include Matchers
+
+    describe "#say" do
+      it "returns an ExpectOutputMatcher" do
+        say("").should be_a(Matchers::OutputMatcher)
+      end
+
+      context "with an explicit timeout" do
+        it "returns an ExpectOutputMatcher" do
+          matcher = say("", 30)
+          matcher.should be_a(Matchers::OutputMatcher)
+          matcher.timeout.should == 30
+        end
+      end
+    end
+
+    describe "#have_exited_with" do
+      it "returns an ExitCodeMatcher" do
+        have_exited_with(1).should be_a(Matchers::ExitCodeMatcher)
+      end
+
+      it "has synonyms" do
+        exit_with(1).should be_a(Matchers::ExitCodeMatcher)
+      end
+    end
+  end
+end

data/spec/runner_spec.rb

@@ -0,0 +1,194 @@
+require 'spec_helper'
+require 'tempfile'
+
+module BlueShell
+  describe Runner do
+    let(:timeout) { 1 }
+
+    describe "running a command" do
+      let(:file) do
+        file = Tempfile.new('blue-shell-runner')
+        sleep 1  # wait one second to make sure touching the file does something measurable
+        file
+      end
+
+      after { file.unlink }
+
+      context "with an invalid command" do
+        it "raises an exception" do
+          expect {
+            BlueShell::Runner.run("false")
+          }.to raise_error(Errors::NonZeroExitCodeError) { |error| error.exit_code.should == 1 }
+        end
+      end
+
+      context "with a valid command" do
+        it "runs a command" do
+          BlueShell::Runner.run("touch -a #{file.path}")
+          file.stat.atime.should > file.stat.mtime
+        end
+      end
+    end
+
+    describe "#success? and #successful?" do
+      context "when the command has a non-zero exit code" do
+        it "returns false" do
+          runner = BlueShell::Runner.run("false") { |runner|
+            runner.wait_for_exit
+          }
+          runner.should_not be_success
+          runner.should_not be_successful
+        end
+      end
+
+      context "when the command has a zero exit code" do
+        it "returns true" do
+          runner = BlueShell::Runner.run("true")
+          runner.should be_success
+          runner.should be_successful
+        end
+      end
+    end
+
+    describe "#expect" do
+      context "when the expected output shows up" do
+        it "returns a truthy value" do
+          BlueShell::Runner.run("echo -n foo") do |runner|
+            expect(runner.expect('foo')).to be_true
+          end
+        end
+      end
+
+      context "when the expected output never shows up" do
+        it "returns nil" do
+          BlueShell::Runner.run("echo the spanish inquisition") do |runner|
+            expect(runner.expect("something else", 0.5)).to be_nil
+          end
+        end
+      end
+
+      context "when the output eventually shows up" do
+        it "returns a truthy value" do
+          BlueShell::Runner.run("ruby #{asset("pause.rb")}") do |runner|
+            expect(runner.expect("finished")).to be_true
+          end
+        end
+      end
+
+      context "backspace" do
+        it "respects the backspace character" do
+          BlueShell::Runner.run("ruby -e 'puts \"foo a\\bbar\"'") do |runner|
+            expect(runner.expect("foo bar")).to be_true
+          end
+        end
+
+        it "does not go beyond the beginning of the line" do
+          BlueShell::Runner.run("ruby -e 'print \"foo abc\nx\\b\\bd\"'") do |runner|
+            expect(runner.expect("foo abc\nd")).to be_true
+          end
+        end
+
+        it "does not go beyond the beginning of the string" do
+          BlueShell::Runner.run("ruby -e 'print \"f\\b\\bbar\"'") do |runner|
+            expect(runner.expect("bar")).to be_true
+          end
+        end
+
+        it "leaves backspaced characters in the buffer until they're overwritten" do
+          BlueShell::Runner.run("ruby -e 'print \"foo abc\\b\\bd\"'") do |runner|
+            expect(runner.expect("foo adc")).to be_true
+          end
+        end
+      end
+
+      context "ansi escape sequences" do
+        it "filters ansi color sequences" do
+          BlueShell::Runner.run("ruby -e 'puts \"\\e[36mblue\\e[0m thing\"'") do |runner|
+            expect(runner.expect("blue thing")).to be_true
+          end
+        end
+      end
+
+      context "expecting multiple branches" do
+        context "and one of them matches" do
+          it "can be passed a hash of values with callbacks, and returns the matched key" do
+            BlueShell::Runner.run("echo 1 3") do |runner|
+              branches = {
+                "1" => proc { 1 },
+                "2" => proc { 2 },
+                "3" => proc { 3 }
+              }
+
+              expect(runner.expect(branches)).to eq "1"
+              expect(runner.expect(branches)).to eq "3"
+            end
+          end
+
+          it "calls the matched callback" do
+            callback = mock!
+            BlueShell::Runner.run("echo 1 3") do |runner|
+              branches = {
+                "1" => proc { callback }
+              }
+              runner.expect(branches)
+            end
+          end
+        end
+
+        context "and none of them match" do
+          it "returns nil when none of the branches match" do
+            BlueShell::Runner.run("echo not_a_number") do |runner|
+              expect(runner.expect({"1" => proc { 1 }}, timeout)).to be_nil
+            end
+          end
+        end
+      end
+    end
+
+    describe "#output" do
+      it "makes the entire command output (so far) available" do
+        BlueShell::Runner.run("echo 0 1 2 3") do |runner|
+          runner.expect("1")
+          runner.expect("3")
+          expect(runner.output).to eq "0 1 2 3"
+        end
+
+      end
+    end
+
+    describe "#send_keys" do
+      it "sends input and expects more output afterward" do
+        BlueShell::Runner.run("ruby #{asset("input.rb")}") do |runner|
+          expect(runner.expect("started")).to be_true
+          runner.send_keys("foo")
+          expect(runner.expect("foo")).to be_true
+        end
+      end
+    end
+
+    context "#exit_code" do
+      it "returns the exit code" do
+        BlueShell::Runner.run("ruby -e 'exit 42'") do |runner|
+          runner.wait_for_exit
+          expect(runner.exit_code).to eq(42)
+        end
+      end
+
+      context "when the command is still running" do
+        it "waits for the command to exit" do
+          BlueShell::Runner.run("sleep 0.5") do |runner|
+            expect(runner.exit_code).to eq(0)
+          end
+        end
+      end
+    end
+
+    context "#exited?" do
+      it "returns false if the command is still running" do
+        BlueShell::Runner.run("sleep 10") do |runner|
+          expect(runner.exited?).to eq false
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'blue-shell'
+require 'rr'
+
+Dir[File.expand_path('../support/**/*.rb', __FILE__)].each do |file|
+  require file
+end
+
+RSpec.configure do |config|
+  config.mock_with :rr
+
+  config.include BlueShell::Helpers
+end
+

data/spec/support/helpers.rb

@@ -0,0 +1,7 @@
+module BlueShell
+  module Helpers
+    def asset(file)
+      File.expand_path("../../assets/#{file}", __FILE__)
+    end
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: blue-shell
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Pivotal Labs
+- Cloud Foundry
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- cfpi-frontend@googlegroups.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- Rakefile
+- lib/blue-shell/buffered_reader_expector.rb
+- lib/blue-shell/errors.rb
+- lib/blue-shell/matchers/exit_code_matcher.rb
+- lib/blue-shell/matchers/output_matcher.rb
+- lib/blue-shell/matchers.rb
+- lib/blue-shell/runner.rb
+- lib/blue-shell/version.rb
+- lib/blue-shell.rb
+- spec/assets/input.rb
+- spec/assets/pause.rb
+- spec/matchers/exit_code_matcher_spec.rb
+- spec/matchers/output_matcher_spec.rb
+- spec/matchers_spec.rb
+- spec/runner_spec.rb
+- spec/spec_helper.rb
+- spec/support/helpers.rb
+homepage: http://github.com/pivotal/blue-shell
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Friendly command-line test runner and matchers for shell scripting in ruby
+  using rspec.
+test_files:
+- spec/assets/input.rb
+- spec/assets/pause.rb
+- spec/matchers/exit_code_matcher_spec.rb
+- spec/matchers/output_matcher_spec.rb
+- spec/matchers_spec.rb
+- spec/runner_spec.rb
+- spec/spec_helper.rb
+- spec/support/helpers.rb