shell_test 0.2.0 → 0.3.0

data/History.rdoc

@@ -1,3 +1,10 @@
+== 0.3.0 2011/10/23
+
+Rewrite and expansion of library to use PTY shell sessions rather than
+individual system commands to test scripts. This marks a significant break in
+functionality. Per-command exit status tests are no longer possible, but
+testing scripts with state is now possible.
+
 == 0.2.0 2011/08/03
 
 * Split out a StringMethods module [issue #7]

data/README.rdoc

@@ -28,43 +28,33 @@ may be used independently, but by including ShellTest you get them all:
       assert_script %{
         $ sh '#{script}' moon
         goodnight moon
-      }
+      }, :exitstatus => 0
     end
   end
 
 ==== {ShellMethods}[link:classes/ShellTest/ShellMethods.html]
 
 Provides the shell testing methods. These methods are designed to input a
-string that looks like terminal input/output. Commands are parsed out of the
-string, run, and then anything printed to stdout is compared to the expected
-output. In addition the exit status is checked for success (0).
-
-Special comments following the first line of a command can turn off
-output/status checking, or specify a different exit status to expect.
+string that looks like terminal input/output. Indeed with PS1 and PS2 set to
+their POSIX defaults, assert_script tests can be created by directly copying
+from the terminal.
 
   require 'shell_test/unit'
-  
   class ShellMethodsExample < Test::Unit::TestCase
     include ShellTest::ShellMethods
-  
-    def test_a_script_using_variables
-      with_env("THING" => "moon") do
+
+    def test_a_script_with_env_variables
+      with_env("THIS" => "moon") do
         assert_script %{
-          $ echo "goodnight $THING"
+          $ THAT="boat"
+          $ echo "goodnight $THIS"
           goodnight moon
+          $ echo "goodnight $THAT"
+          goodnight boat
         }
       end
     end
-    
-    def test_multiple_commands
-      assert_script %{
-        $ echo one
-        one
-        $ echo two
-        two
-      }
-    end
-  
+
     def test_multiline_commands
       assert_script %{
         $ for n in one two; do
@@ -74,28 +64,35 @@ output/status checking, or specify a different exit status to expect.
         two
       }
     end
- 
-    def test_exit_statuses
-      assert_script %{
-        $ true  # [0]
-        $ false # [1]
-      }
-    end
-    
-    def test_exit_status_and_not_ouptut
+
+    def test_script_with_overall_and_per_command_timeouts
       assert_script %{
-        $ date  # [0] ...
-      }
+        $ sleep 0.1  # [0.5]
+        $ sleep 0.1  # [0.5]
+      }, :max_run_time => 1
     end
-    
-    def test_output_with_inline_regexps
+
+    def test_scripts_where_the_output_is_variable
       assert_script_match %{
         $ cal
         :...:
-        Su Mo Tu We Th Fr Sa
-        :...:
+        Su Mo Tu We Th Fr Sa:. *.:
+        :....:
       }
     end
+
+    def test_scripts_that_take_input
+      assert_script %{
+        $ sudo echo 'sorry i cant do that dave'
+        Password:{{notIt}}
+        Sorry, try again.
+        Password:{{mayBeThis}}
+        Sorry, try again.
+        Password:{{cr@pWhatIsIt}}
+        Sorry, try again.
+        sudo: 3 incorrect password attempts
+      }, :max_run_time => 10
+    end
   end
 
 ==== {FileMethods}[link:classes/ShellTest/FileMethods.html]
@@ -130,17 +127,11 @@ ShellTest is available as a gem[http://rubygems.org/gems/shell_test].
 
 To get started, checkout the code from GitHub[http://github.com/thinkerbot/shell_test] and run:
 
-  git clone git://github.com/thinkerbot/shell_test.git
-  cd shell_test
   rake test
 
-To test against multiple platforms I suggest using rvm.  In that case:
-
-  rvm rake test
-
 Please report any issues {here}[http://github.com/thinkerbot/shell_test/issues].
 
 == Info
 
-Developer:: {Simon Chiang}[http://thinkerbot.posterous.com]
+Developer:: {Simon Chiang}[http://github.com/thinkerbot]
 License:: {MIT-Style}[link:files/MIT-LICENSE.html]

data/lib/shell_test/env_methods.rb

@@ -0,0 +1,44 @@
+module ShellTest
+  module EnvMethods
+    module_function
+
+    # Sets the specified ENV variables and returns the *current* env.
+    # If replace is true, current ENV variables are replaced; otherwise
+    # the new env variables are simply added to the existing set.
+    def set_env(env={}, replace=false)
+      current_env = {}
+      ENV.each_pair do |key, value|
+        current_env[key] = value
+      end
+
+      ENV.clear if replace
+
+      env.each_pair do |key, value|
+        if value.nil?
+          ENV.delete(key)
+        else
+          ENV[key] = value
+        end
+      end if env
+
+      current_env
+    end
+
+    # Sets the specified ENV variables for the duration of the block.
+    # If replace is true, current ENV variables are replaced; otherwise
+    # the new env variables are simply added to the existing set.
+    #
+    # Returns the block return.
+    def with_env(env={}, replace=false)
+      current_env = nil
+      begin
+        current_env = set_env(env, replace)
+        yield
+      ensure
+        if current_env
+          set_env(current_env, true)
+        end
+      end
+    end
+  end
+end

data/lib/shell_test/file_methods.rb

@@ -128,10 +128,14 @@ module ShellTest
     include StringMethods
     extend ModuleMethods
 
+    # Returns the absolute path to the current working directory.
+    attr_reader :user_dir
+
     # Calls cleanup to remove any files left over from previous test runs (for
     # instance by running with a flag to keep outputs).
     def setup
       super
+      @user_dir = Dir.pwd
       cleanup
     end
 
@@ -161,11 +165,6 @@ module ShellTest
       ENV["KEEP_OUTPUTS"] == "true"
     end
 
-    # Returns the absolute path to the current working directory.
-    def user_dir
-      @user_dir   ||= File.expand_path('.')
-    end
-
     # Returns the absolute path to a directory specific to the current test
     # class, specifically the class.class_dir expanded relative to the
     # user_dir.
@@ -211,7 +210,9 @@ module ShellTest
     # Creates a directory under method_dir.
     def prepare_dir(relative_path)
       target_dir = path(relative_path)
-      FileUtils.mkdir_p(target_dir)
+      unless File.directory?(target_dir)
+        FileUtils.mkdir_p(target_dir)
+      end
       target_dir
     end
 
@@ -223,7 +224,7 @@ module ShellTest
         FileUtils.rm(target)
       else
         target_dir = File.dirname(target)
-        FileUtils.mkdir_p(target_dir)
+        FileUtils.mkdir_p(target_dir) unless File.exists?(target_dir)
       end
 
       FileUtils.touch(target)

data/lib/shell_test/regexp_escape.rb

@@ -1,23 +1,25 @@
 module ShellTest
   # RegexpEscape is a subclass of regexp that escapes all but the text in a
-  # special escape sequence.  This allows the creation of complex regexps
-  # to match, for instance, console output.
+  # special escape sequence.  This allows the creation of complex regexps to
+  # match, for instance, console output.
   #
-  # The RegexpEscape.escape (or equivalently the quote) method does the
-  # work; all regexp-active characters are escaped except for characters
-  # enclosed by ':.' and '.:' delimiters.
+  # The RegexpEscape.escape (or equivalently the quote) method does the work;
+  # all regexp-active characters are escaped except for characters enclosed by
+  # ':.' and '.:' delimiters.
   #
   #   RegexpEscape.escape('reg[exp]+ chars. are(quoted)')       # => 'reg\[exp\]\+\ chars\.\ are\(quoted\)'
   #   RegexpEscape.escape('these are not: :.a(b*)c.:')          # => 'these\ are\ not:\ a(b*)c'
   #
-  # In addition, all-period regexps are automatically upgraded to '.*?';
-  # use the '.{n}' notation to specify n arbitrary characters.
+  # All-period regexps are treated specially.  A single period is translated
+  # to '.*?' to lazily match anything on a single line.  Multiple periods are
+  # translated to '(?:(?m).*?)' to lazily match anything actoss multiple
+  # lines. Use the '.{n}' notation to specify n arbitrary characters.
   #
-  #   RegexpEscape.escape('_:..:_:...:_:....:')        # => '_.*?_.*?_.*?'
-  #   RegexpEscape.escape(':..{1}.:')                  # => '.{1}'
+  #   RegexpEscape.escape('a:...:b:....:c')        # => 'a.*?b(?:(?m).*?)c'
+  #   RegexpEscape.escape('a:..{1}.:b')            # => 'a.{1}b'
   #
-  # RegexpEscape instances are initialized using the escaped input string
-  # and return the original string upon to_s.
+  # RegexpEscape instances are initialized using the escaped input string and
+  # return the original string upon to_s.
   #
   #   str = %q{
   #   a multiline
@@ -50,8 +52,14 @@ module ShellTest
         substituents = []
         str.scan(ESCAPE_SEQUENCE) do
           regexp_str = $&[2...-2]
-          regexp_str = ".*?" if regexp_str =~ /^\.*$/
-          substituents << regexp_str
+          substituents << case regexp_str
+          when '.'
+            ".*?"
+          when /\A\.+\z/
+            "(?:(?m).*?)"
+          else
+            regexp_str
+          end
         end
         substituents << ""
 

data/lib/shell_test/shell_methods.rb

@@ -1,84 +1,20 @@
 require 'shell_test/regexp_escape'
-require 'shell_test/command_parser'
 require 'shell_test/string_methods'
+require 'shell_test/shell_methods/session'
 
 module ShellTest
   module ShellMethods
     include StringMethods
+    include EnvMethods
 
-    def setup
-      super
-      @notify_method_name = true
+    def pty(script, options={}, &block)
+      _pty outdent(script), options, &block
     end
 
-    # Parse a script into an array of [cmd, output, status] triplets.
-    def parse_script(script, options={})
-      CommandParser.new(options).parse(script)
-    end
-
-    # Returns true if the ENV variable 'VERBOSE' is true.  When verbose,
-    # ShellTest prints the expanded commands of sh_test to $stdout.
-    def verbose?
-      verbose = ENV['VERBOSE']
-      verbose && verbose =~ /^true$/i ? true : false
-    end
-
-    # Sets the specified ENV variables and returns the *current* env.
-    # If replace is true, current ENV variables are replaced; otherwise
-    # the new env variables are simply added to the existing set.
-    def set_env(env={}, replace=false)
-      current_env = {}
-      ENV.each_pair do |key, value|
-        current_env[key] = value
-      end
-
-      ENV.clear if replace
-
-      env.each_pair do |key, value|
-        if value.nil?
-          ENV.delete(key)
-        else
-          ENV[key] = value
-        end
-      end if env
-
-      current_env
-    end
-
-    # Sets the specified ENV variables for the duration of the block.
-    # If replace is true, current ENV variables are replaced; otherwise
-    # the new env variables are simply added to the existing set.
-    #
-    # Returns the block return.
-    def with_env(env={}, replace=false)
-      current_env = nil
-      begin
-        current_env = set_env(env, replace)
-        yield
-      ensure
-        if current_env
-          set_env(current_env, true)
-        end
-      end
-    end
-
-    def sh(cmd)
-      if @notify_method_name && verbose?
-        @notify_method_name = false
-        puts
-        puts method_name 
-      end
-
-      start  = Time.now
-      result = `#{cmd}`
-      finish = Time.now
-
-      if verbose?
-        elapsed = "%.3f" % [finish-start]
-        puts "  (#{elapsed}s) #{cmd}"
-      end
-
-      result
+    def _pty(script, options={}, &block)
+      session = Session.new(options)
+      session.parse(script, options, &block)
+      session.run
     end
 
     def assert_script(script, options={})
@@ -86,11 +22,26 @@ module ShellTest
     end
 
     def _assert_script(script, options={})
-      parse_script(script, options).each do |cmd, output, status|
-        result = sh(cmd)
+      pty = _pty(script, options) do |session, expected, actual|
+        expected = expand_ctrl_chars(expected)
+        actual   = expand_ctrl_chars(actual)
+
+        _assert_str_equal expected, actual do
+          session.summary %Q{
+%s (elapsed: %.2fs max: %.2fs)
+=========================================================
+%s
+-------------------- expected output --------------------
+#{whitespace_escape(expected)}
+------------------------ but was ------------------------
+#{whitespace_escape(actual)}
+=========================================================
+}
+        end
+      end
 
-        _assert_str_equal(output, result, cmd) if output
-        assert_equal(status, $?.exitstatus, cmd)  if status
+      if status = options[:exitstatus]
+        assert_equal(status, pty.status.exitstatus)
       end
     end
 
@@ -99,11 +50,26 @@ module ShellTest
     end
 
     def _assert_script_match(script, options={})
-      parse_script(script, options).each do |cmd, output, status|
-        result = sh(cmd)
+      pty = _pty(script, options) do |session, expected, actual|
+        expected = expand_ctrl_chars(expected)
+        actual   = expand_ctrl_chars(actual)
+
+        _assert_str_match expected, actual do
+          session.summary %Q{
+%s (%.2f:%.2fs)
+=========================================================
+%s
+----------------- expected output like ------------------
+#{whitespace_escape(expected)}
+------------------------ but was ------------------------
+#{whitespace_escape(actual)}
+=========================================================
+}
+        end
+      end
 
-        _assert_str_match(output, result, cmd)       if output
-        assert_equal(status, $?.exitstatus, cmd) if status
+      if status = options[:exitstatus]
+        assert_equal(status, pty.status.exitstatus)
       end
     end
   end

data/lib/shell_test/shell_methods/agent.rb

@@ -0,0 +1,135 @@
+require 'shell_test/shell_methods/timer'
+
+module ShellTest
+  module ShellMethods
+    # Agent wraps a PTY master-slave pair and provides methods for doing reads
+    # and writes. The expect method is inspired by the IO.expect method in the
+    # stdlib, but tailored to allow for better timeout control.
+    class Agent
+
+      # The pty master
+      attr_reader :master
+
+      # The pty slave
+      attr_reader :slave
+
+      # The timer managing read timeouts.  The timer ensures that the timeouts
+      # used by expect are never negative, or nil to indicate no timeout.
+      #
+      # If implementing a custom timer, note that timeouts are set on the
+      # timer using `timer.timeout=` and retrieved via `timer.timeout`.
+      attr_reader :timer
+
+      # A hash of [name, regexp] pairs mapping logical names to prompts.
+      attr_reader :prompts
+
+      def initialize(master, slave, timer, prompts={})
+        @master = master
+        @slave  = slave
+        @timer  = timer
+        @prompts = prompts
+      end
+
+      def on(prompt, input, timeout=nil)
+        output = expect(prompt, timeout)
+        write(input)
+        output
+      end
+
+      # Reads from the slave until the prompt (a regexp) is matched and
+      # returns the resulting string.  If a nil prompt is given then expect
+      # reads until the slave eof.
+      #
+      # A timeout may be given. If the slave doesn't produce the expected
+      # string within the timeout then expect raises a ReadError. A ReadError
+      # will be also be raised if the slave eof is reached before the prompt
+      # matches.
+      def expect(prompt, timeout=nil)
+        regexp = prompts[prompt] || prompt
+        timer.timeout = timeout
+
+        buffer = ''
+        while true
+          timeout = timer.timeout
+
+          # Use read+select instead of read_nonblock to avoid polling in a
+          # tight loop.  Don't bother with readpartial and partial lengths. It
+          # would be an optimization, especially because the regexp matches
+          # each loop, but adds complexity because expect could read past the
+          # end of the regexp and it is unlikely to be necessary in test
+          # scenarios (ie this is not meant to be a general solution).
+          unless IO.select([slave],nil,nil,timeout)
+            msg = "timeout waiting for %s after %.2fs" % [regexp ? regexp.inspect : 'EOF', timeout]
+            raise ReadError.new(msg, buffer)
+          end
+
+          begin
+            c = slave.read(1)
+          rescue Errno::EIO
+            # On some linux (ex ubuntu) read can return an eof or fail with
+            # an EIO error when a terminal disconnect occurs and an EIO
+            # condition occurs - the exact behavior is unspecified but the
+            # meaning is the same... no more data is available, so break.
+            c = nil
+          end
+
+          if c.nil?
+            if regexp.nil?
+              break
+            else
+              raise ReadError.new("end of file reached", buffer)
+            end
+          end
+
+          buffer << c
+
+          if regexp && buffer =~ regexp
+            break
+          end
+        end
+        buffer
+      end
+
+      # Read to the end of the slave.  Raises a ReadError if the slave eof is
+      # not reached within the timeout.
+      def read(timeout=nil)
+        expect nil, timeout
+      end
+
+      # Writes to the master. A timeout may be given. If the master doesn't
+      # become available for writing within the timeout then write raises an
+      # WriteError.
+      def write(input, timeout=nil)
+        unless IO.select(nil,[master],nil,timeout)
+          raise WriteError.new("timeout waiting for master")
+        end
+        master.print input
+      end
+
+      # Closes the master and slave.
+      def close
+        unless master.closed?
+          master.close
+        end
+        unless slave.closed?
+          slave.close
+        end
+      end
+
+      # Raised when Agent writes timeout.
+      class WriteError < RuntimeError
+      end
+
+      # Raised when Agent reads fail or timeout.
+      class ReadError < RuntimeError
+        # The buffer containing whatever had been read at the time of error.
+        attr_reader :buffer
+
+        def initialize(message, buffer)
+          @buffer = buffer
+          super message
+        end
+      end
+    end
+  end
+end

data/lib/shell_test/shell_methods/session.rb

@@ -0,0 +1,293 @@
+require 'shell_test/env_methods'
+require 'shell_test/shell_methods/agent'
+require 'shell_test/shell_methods/utils'
+require 'strscan'
+
+module ShellTest
+  module ShellMethods
+
+    # Session is an engine for running shell sessions.
+    class Session
+      include EnvMethods
+      include Utils
+
+      DEFAULT_SHELL = '/bin/sh'
+      DEFAULT_PS1   = '$ '
+      DEFAULT_PS2   = '> '
+      DEFAULT_STTY  = '-echo -onlcr'
+      DEFAULT_MAX_RUN_TIME = 1
+
+      # The session shell
+      attr_reader :shell
+
+      # The shell PS1
+      attr_reader :ps1
+
+      # The shell PS2
+      attr_reader :ps2
+
+      # Aguments string passed stty on run
+      attr_reader :stty
+
+      # The session timer, used by agents to determine timeouts
+      attr_reader :timer
+
+      # The maximum run time for the session
+      attr_reader :max_run_time
+
+      # An array of entries like [prompt, input, max_run_time, callback] that
+      # indicate each step of a session.  See the on method for adding steps.
+      attr_reader :steps
+
+      # A log of the output at each step (set during run)
+      attr_reader :log
+
+      # A Process::Status for the session (set by run)
+      attr_reader :status
+
+      def initialize(options={})
+        @shell = options[:shell] || DEFAULT_SHELL
+        @ps1   = options[:ps1]   || DEFAULT_PS1
+        @ps2   = options[:ps2]   || DEFAULT_PS2
+        @stty  = options[:stty]  || DEFAULT_STTY
+        @timer = options[:timer] || Timer.new
+        @max_run_time = options[:max_run_time] || DEFAULT_MAX_RUN_TIME
+        @steps   = [[nil, nil, nil, nil]]
+        @log     = []
+        @status  = nil
+        @prompts = {
+          :ps1 => /#{Regexp.escape(ps1)}/,
+          :ps2 => /#{Regexp.escape(ps2)}/
+        }
+      end
+
+      # Define a step.  At each step:
+      #
+      # 1. The session waits until the prompt is matched
+      # 2. The input is written to the shell (if given)
+      # 3. The output passed to the callback (if given)
+      #
+      # If the next prompt (or an EOF if there is no next prompt) is not
+      # reached within max_run_time then a ReadError occurs.  Special
+      # considerations:
+      #
+      # * The prompt should be a regular expression, :ps1, or :ps2.
+      # * A nil max_run_time indicates no maximum run time - which more
+      #   accurately means the input can go until the overall max_run_time for
+      #   the session runs out.
+      # * The output passed to the callback will include the string matched by
+      #   the next prompt, if present.
+      #
+      # Returns self.
+      def on(prompt, input=nil, max_run_time=nil, &callback) # :yields: output
+        if prompt.nil?
+          raise ArgumentError, "no prompt specified"
+        end
+
+        # Stagger assignment of step arguments so that the callback will be
+        # recieve the output of the input. Not only is this more intuitive, it
+        # ensures the last step will read to EOF (which expedites waiting on
+        # the session to terminate).
+        last = steps.last
+        last[0] = prompt
+        last[1] = input
+        last[2] = max_run_time
+
+        steps << [nil, nil, nil, callback]
+        self
+      end
+
+      def split(str)
+        scanner = StringScanner.new(str)
+        scanner.scan_until(/(#{@prompts[:ps1]})/)
+        scanner.pos -= scanner[1].to_s.length
+
+        args = []
+        while output = scanner.scan_until(/(#{@prompts[:ps1]}|#{@prompts[:ps2]}|\{\{(.*?)\}\})/)
+          match = scanner[1]
+          input = scanner[2] ? "#{scanner[2]}\n" : scanner.scan_until(/\n/)
+
+          max_run_time = -1
+          input.sub!(/\#\s*\[(\d+(?:\.\d+)?)\].*$/) do
+            max_run_time = $1.to_f
+            nil
+          end
+
+          case match
+          when ps1
+            prompt = :ps1
+            if max_run_time == -1
+              max_run_time = nil
+            end
+          when ps2
+            prompt = :ps2
+          else
+            output = output.chomp(match)
+            prompt = /^#{output.split("\n").last}\z/
+          end
+
+          args << output
+          args << prompt
+          args << input
+          args << max_run_time
+        end
+
+        args << scanner.rest
+        args
+      end
+
+      # Parses a terminal snippet into steps that a Session can run, and adds
+      # those steps to self.  The snippet should utilize ps1 and ps2 as set on
+      # self. An exit command is added unless the :noexit option is set to
+      # true.
+      #
+      #   session = Session.new
+      #   session.parse %{
+      #   $ echo abc
+      #   abc
+      #   }
+      #   session.run.result   # => "$ echo abc\nabc\n$ exit\nexit\n"
+      #
+      # Steps are registered with a callback block, if given, to recieve the
+      # expected and actual outputs during run.  Normally the callback is used
+      # to validate that the run is going as planned.
+      def parse(script, options={}, &block)
+        args = split(script)
+        args.shift # ignore script before first prompt
+
+        if options[:noexit]
+          args.pop
+        else
+          args.last << ps1
+          args.concat [:ps1, "exit\n", nil, nil]
+        end
+
+        while !args.empty?
+          prompt = args.shift
+          input  = args.shift
+          max_run_time = args.shift
+          output = args.shift
+          callback = make_callback(output, &block)
+
+          on(prompt, input, max_run_time, &callback)
+        end
+
+        self
+      end
+
+      # Spawns a PTY shell session and yields an Agent to the block.  The
+      # session is logged to log and the final exit status set into status
+      # (any previous values are overwritten).
+      #
+      # ==== ENV variables
+      #
+      # PS1 and PS2 are set into ENV for the duration of the block and so in
+      # most cases the shell inherits those values.  Keep in mind, however,
+      # that the shell config scripts can set these variables and on some
+      # distributions (ex SLES 10) the config script do not respect prior
+      # values.
+      #
+      def spawn
+        with_env('PS1' => ps1, 'PS2' => ps2) do
+          @log = []
+          @status = super(shell) do |master, slave|
+            agent = Agent.new(master, slave, timer, @prompts)
+            timer.start(max_run_time)
+
+            if stty
+              # It would be lovely to work this into steps somehow, or to set
+              # the stty externally like:
+              #
+              #   system("stty #{stty} < '#{master.path}'")
+              #
+              # Unfortunately the former complicates result and the latter
+              # doesn't work.  In tests the stty settings DO get set but they
+              # don't refresh in the pty.
+              log << agent.on(:ps1, "stty #{stty}\n")
+              log << agent.on(:ps1, "echo $?\n")
+              log << agent.on(:ps1, "\n")
+
+              unless log.last == "0\n#{ps1}"
+                raise "stty failure\n#{summary}"
+              end
+
+              log.clear
+            end
+
+            begin
+              yield agent
+            rescue Agent::ReadError
+              log << $!.buffer
+              $!.message << "\n#{summary}"
+              raise
+            end
+
+            timer.stop
+            agent.close
+          end
+        end
+        self
+      end
+
+      # Runs each of steps within a shell session and collects the
+      # inputs/outputs into log. After run the exit status of the session is
+      # set into status.
+      def run
+        spawn do |agent|
+          timeout  = nil
+          steps.each do |prompt, input, max_run_time, callback|
+            buffer = agent.expect(prompt, timeout)
+            log << buffer
+
+            if callback
+              callback.call buffer
+            end
+
+            if input
+              log << input
+              agent.write(input)
+            end
+
+            timeout = max_run_time
+          end
+        end
+      end
+
+      # Returns what would appear to the user at the current point in the
+      # session (with granularity of an input/output step).
+      #
+      # Currently result ONLY works as intended when stty is set to turn off
+      # input echo and output carriage returns, either with '-echo -onlcr'
+      # (the default) or 'raw'.  Otherwise the inputs can appear twice in the
+      # result and there will be inconsistent end-of-lines.
+      def result
+        log.join
+      end
+
+      # Formats the status of self into a string. A format string can be
+      # provided - it is evaluated using '%' using arguments: [shell,
+      # elapsed_time, result]
+      def summary(format=nil)
+        (format || %Q{
+%s (elapsed: %.2fs max: %.2fs)
+=========================================================
+%s
+=========================================================
+}) % [shell, timer.elapsed_time, max_run_time, result]
+      end
+
+      private
+
+      # helper to make a callback for validating output
+      def make_callback(output) # :nodoc:
+        if output && block_given?
+          lambda do |actual|
+            yield(self, output, actual)
+          end
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/shell_test/shell_methods/timer.rb

@@ -0,0 +1,71 @@
+module ShellTest
+  module ShellMethods
+    class Timer
+      attr_reader :clock
+      attr_reader :start_time
+      attr_reader :stop_time
+      attr_reader :step_time
+
+      def initialize(clock=Time)
+        @clock = clock
+        reset
+      end
+
+      def current_time
+        clock.now.to_f
+      end
+
+      def reset
+        @start_time = nil
+        @stop_time  = nil
+        @step_time  = 0
+      end
+
+      def start(max_run_time=60)
+        reset
+        @start_time = current_time
+        @stop_time  = start_time + max_run_time
+        @step_time  = stop_time
+      end
+
+      def running?
+        start_time.nil? || stop_time.nil? ? false : true
+      end
+
+      def elapsed_time
+        current_time - start_time
+      end
+
+      def stop
+        if running?
+          elapsed = elapsed_time
+          reset
+          elapsed
+        else
+          nil
+        end
+      end
+
+      def timeout=(timeout)
+        unless running?
+          raise "cannot set timeout unless running"
+        end
+
+        case
+        when timeout.nil?
+          @step_time = stop_time
+        when timeout < 0 
+          step_time
+        else
+          mtime = current_time + timeout
+          @step_time = mtime > stop_time ? stop_time : mtime
+        end
+      end
+
+      def timeout
+        timeout = step_time - current_time
+        timeout < 0 ? 0 : timeout
+      end
+    end
+  end
+end

data/lib/shell_test/shell_methods/utils.rb

@@ -0,0 +1,53 @@
+require 'pty'
+
+module ShellTest
+  module ShellMethods
+    module Utils
+      module_function
+
+      # Spawns a PTY session and returns the Process::Status for the session
+      # upon completion. The PTY process is killed upon an unhandled error
+      # (but the error is re-raised for further handling).
+      #
+      # Note that $? is set by spawn but is not reliable until 1.9.2 (ish).
+      # Prior to that PTY used a cleanup thread that would wait on a spawned
+      # process and raise a PTY::ChildExited error in some cases.  As a result
+      # manual calls to Process.wait (which would set $?) cause a race
+      # condition. Rely on the output of spawn instead.
+      def spawn(cmd)
+        PTY.spawn(cmd) do |slave, master, pid|
+          begin
+            yield(master, slave)
+            Process.wait(pid)
+
+          rescue PTY::ChildExited
+            # handle a ChildExited error on 1.8.6 and 1.8.7 as a 'normal' exit
+            # route.  1.9.2 does not exit this way.
+            return $!.status
+
+          rescue Exception
+            # cleanup the pty on error
+            Process.kill(9, pid)
+
+            # clearing the slave allows the wait to complete faster
+            while IO.select([slave],nil,nil,0.1)
+              begin
+                break unless slave.read(1)
+              rescue Errno::EIO
+                break
+              end
+            end
+
+            # any wait can cause a ChildExited error so account for that here
+            # - the $? is indeterminate in this case prior to 1.9.2
+            Process.wait(pid) rescue PTY::ChildExited
+
+            raise
+          end
+        end
+
+        $?
+      end
+    end
+  end
+end

data/lib/shell_test/string_methods.rb

@@ -3,19 +3,21 @@ module ShellTest
     # Asserts whether or not the a and b strings are equal, with a more
     # readable output than assert_equal for large strings (especially large
     # strings with significant whitespace).
-    def assert_str_equal(a, b, msg=nil)
-      _assert_str_equal outdent(a), b, msg
+    def assert_str_equal(a, b, msg=nil, &block)
+      _assert_str_equal outdent(a), b, msg, &block
     end
 
+    # Same as assert_str_equal but does not outdent.
     def _assert_str_equal(a, b, msg=nil)
       if a == b
         assert true
       else
-        flunk %Q{
+        flunk block_given? ? yield(a, b) : %Q{
+=========================================================
 #{msg}
-==================== expected output ====================
+-------------------- expected output --------------------
 #{whitespace_escape(a)}
-======================== but was ========================
+------------------------ but was ------------------------
 #{whitespace_escape(b)}
 =========================================================
 }
@@ -26,12 +28,13 @@ module ShellTest
     # provides a more readable output in the case of a failure as compared
     # with assert_match.
     #
-    # If a is a string it is turned into a RegexpEscape.
-    def assert_str_match(a, b, msg=nil)
+    # If a is a string then it is turned into a RegexpEscape.
+    def assert_str_match(a, b, msg=nil, &block)
       a = outdent(a) if a.kind_of?(String)
-      _assert_str_match a, b, msg
+      _assert_str_match a, b, msg, &block
     end
 
+    # Same as assert_str_match but does not outdent.
     def _assert_str_match(a, b, msg=nil)
       if a.kind_of?(String)
         a = RegexpEscape.new(a)
@@ -40,25 +43,33 @@ module ShellTest
       if b =~ a
         assert true
       else
-        flunk %Q{
+        flunk block_given? ? yield(a,b) : %Q{
+=========================================================
 #{msg}
-================= expected output like ==================
+----------------- expected output like ------------------
 #{whitespace_escape(a)}
-======================== but was ========================
+------------------------ but was ------------------------
 #{whitespace_escape(b)}
 =========================================================
 }
       end
     end
 
-    # helper for stripping indentation off a string
+    # Indents each line of str as specified.
+    def indent(str, indent='  ')
+      str.split("\n").collect do |frag|
+        "#{indent}#{frag}"
+      end.join("\n")
+    end
+
+    # Strips indentation off of the input string.
     def outdent(str)
       str =~ /\A(?:\s*?\n)( *)(.*)\z/m ? $2.gsub!(/^ {0,#{$1.length}}/, '') : str
     end
 
-    # helper for formatting escaping whitespace into readable text
+    # Escapes non-printable characters into readable text.
     def whitespace_escape(str)
-      str.to_s.gsub(/\s/) do |match|
+      str = str.to_s.gsub(/\s/) do |match|
         case match
         when "\n" then "\\n\n"
         when "\t" then "\\t"
@@ -67,6 +78,28 @@ module ShellTest
         else match
         end
       end
+      str.gsub!("\b", "\\b")
+      str.gsub!("\a", "\\a")
+      str.split("\0").join('\\0')
+    end
+
+    # Expands non-printable characters (ie control characters) in str to their
+    # common print equivalents. Specifically:
+    #
+    #   ctrl char         before    after
+    #   null              "ab\0c"    "abc"
+    #   bell              "ab\ac"    "abc"
+    #   backspace         "ab\bc"    "ac"
+    #   horizonal tab     "ab\tc"    "ab\tc"
+    #   line feed         "ab\nc"    "ab\nc"
+    #   form feed         "ab\fc"    "ab\n  c"
+    #   carraige return   "ab\rc"    "c"
+    #
+    def expand_ctrl_chars(str)
+      str = str.gsub(/^.*?\r/, '')
+      str.gsub!(/(\A#{"\b"}|.#{"\b"}|#{"\a"}|#{"\0"})/m, '')
+      str.gsub!(/(^.*?)\f/) { "#{$1}\n#{' ' * $1.length}" }
+      str
     end
   end
 end

data/lib/shell_test/version.rb

@@ -1,3 +1,3 @@
 module ShellTest
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: shell_test
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: 
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-03 00:00:00 -06:00
+date: 2011-10-23 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
@@ -32,10 +32,14 @@ extra_rdoc_files:
 - MIT-LICENSE
 files: 
 - lib/shell_test.rb
-- lib/shell_test/command_parser.rb
+- lib/shell_test/env_methods.rb
 - lib/shell_test/file_methods.rb
 - lib/shell_test/regexp_escape.rb
 - lib/shell_test/shell_methods.rb
+- lib/shell_test/shell_methods/agent.rb
+- lib/shell_test/shell_methods/session.rb
+- lib/shell_test/shell_methods/timer.rb
+- lib/shell_test/shell_methods/utils.rb
 - lib/shell_test/string_methods.rb
 - lib/shell_test/unit.rb
 - lib/shell_test/unit/shim.rb
@@ -45,8 +49,8 @@ files:
 - MIT-LICENSE
 has_rdoc: true
 homepage: ""
-licenses: []
-
+licenses: 
+- MIT
 post_install_message: 
 rdoc_options: 
 - --main

data/lib/shell_test/command_parser.rb

@@ -1,67 +0,0 @@
-module ShellTest
-  class CommandParser
-    attr_reader :ps1
-    attr_reader :ps2
-
-    def initialize(options={})
-      options = {
-        :ps1 => '$ ',
-        :ps2 => '> '
-      }.merge(options)
-
-      @ps1 = options[:ps1]
-      @ps2 = options[:ps2]
-    end
-
-    def parse_cmd(cmd)
-      cmd =~ /.*?#\s*(?:\[(\d+)\])?\s*(\.{3})?/
-      exit_status = $1 ? $1.to_i : 0
-      output = $2 ? nil : ""
-
-      [cmd, output, exit_status]
-    end
-
-    def parse(script)
-      commands = []
-
-      command, output, exit_status = nil, "", 0
-      script.each_line do |line|
-        case
-        when line.index(ps1) == 0
-          if command
-            commands << [command, output, exit_status]
-          end
-
-          command, output, exit_status = parse_cmd lchomp(ps1, line)
-
-        when command.nil?
-          unless line.strip.empty?
-            command, output, exit_status = parse_cmd(line)
-          end
-
-        when line.index(ps2) == 0
-          command << lchomp(ps2, line)
-
-        when output.nil?
-          output = line
-
-        else
-          output << line
-        end
-      end
-
-      if command
-        commands << [command, output, exit_status]
-      end
-
-      commands
-    end
-
-    private
-
-    def lchomp(prefix, line) # :nodoc:
-      length = prefix.length
-      line[length, line.length - length]
-    end
-  end
-end