shell_test 0.3.0 → 0.4.0

data/History.rdoc

@@ -1,3 +1,10 @@
+== 0.4.0 2011/11/01
+
+Renames prepare methods in FileMethods to setup_file and setup_dir, and
+changes numerous class methods for setting up method dir cleanup.
+
+* Parser now escapes special chars in inline prompts [issue #16]
+
 == 0.3.0 2011/10/23
 
 Rewrite and expansion of library to use PTY shell sessions rather than

data/README.rdoc

@@ -16,20 +16,44 @@ ShellTest builds on modules that provide specific functionality. The modules
 may be used independently, but by including ShellTest you get them all:
 
   require 'shell_test/unit'
-  
+
   class ShellTestExample < Test::Unit::TestCase
     include ShellTest
-  
+
     def test_a_script
-      script = prepare('script.sh') do |io|
-        io.puts "echo goodnight $1"
-      end
-  
+      script = setup_file 'script.sh', %{
+        echo goodnight $1
+      }
+
       assert_script %{
         $ sh '#{script}' moon
         goodnight moon
       }, :exitstatus => 0
     end
+
+    def test_a_script_that_takes_input
+      script = setup_file 'script.sh', %{
+        stty -echo
+        while true; do
+          printf "Do you wish to continue? [y/n]: "
+          read answer
+          case $answer in
+              y ) printf "\nOk!\n"; break;;
+              n ) printf "\nToo bad.\n"; break;;
+              * ) printf "\nPlease answer y or n.\n";;
+          esac
+        done
+        stty echo
+      }
+
+      assert_script %{
+        $ sh '#{script}'
+        Do you wish to continue? [y/n]: {{hmmm}}
+        Please answer y or n.
+        Do you wish to continue? [y/n]: {{y}}
+        Ok!
+      }
+    end
   end
 
 ==== {ShellMethods}[link:classes/ShellTest/ShellMethods.html]
@@ -81,17 +105,13 @@ from the terminal.
       }
     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
+    def test_scripts_where_alternate_prompts_are_needed
+      with_env('PS1' => '% ') do
+        assert_script %{
+          % echo '$ $ $'
+          $ $ $
+        }
+      end
     end
   end
 
@@ -99,7 +119,8 @@ from the terminal.
 
 Sets up a temporary, test-specific directory for working with files. This
 approach is better in most cases than using Tempfile because you can flag the
-directory to be saved on a failure (using ENV['KEEP_OUTPUTS']='true').
+directory to be saved on a failure (using ENV['KEEP_OUTPUTS']='true') and
+immediately know where to look for your files.
 
 By default the directory is guessed based off of the test file and test
 method. If this example were located in the 'test/file_methods_example.rb'
@@ -107,12 +128,12 @@ file, then the directory for the test case would be
 'test/file_methods_example/test_preparation_of_a_test_specific_file'.
 
   require 'shell_test/unit'
-  
+
   class FileMethodsExample < Test::Unit::TestCase
     include ShellTest::FileMethods
 
-    def test_preparation_of_a_test_specific_file
-      path = prepare('dir/file.txt') {|io| io << 'content' }
+    def test_setup_of_a_test_specific_file
+      path = setup_file('dir/file.txt') {|io| io << 'content' }
       assert_equal "content", File.read(path)
     end
   end

data/lib/shell_test/file_methods.rb

@@ -6,29 +6,47 @@ module ShellTest
     module ClassMethods
       attr_accessor :class_dir
 
-      attr_reader :cleanup_method_registry
-
-      def cleanup_methods
-        @cleanup_methods ||= begin
-          cleanup_methods = {}
+      # A registry tracking paths_to_cleanup for the current class.
+      attr_reader :paths_to_cleanup_registry
+
+      # A hash of (method_name, [relative_path]) pairs identifying which
+      # relative paths on each method have been marked on this class or
+      # inherited from ancestors. Entries in paths_to_cleanup should not be
+      # edited directly.  Instead use:
+      #
+      #   cleanup         : turn on cleanup for methods
+      #   do_not_cleanup  : turn off cleanup for methods
+      #   default_paths_to_cleanup : set the default paths to cleanup
+      # 
+      # Or if you need very precise editing, use (with the same semantics as
+      # {define/remove/undef}_method):
+      #
+      #   define_paths_to_cleanup
+      #   remove_paths_to_cleanup
+      #   undef_paths_to_cleanup
+      #
+      def paths_to_cleanup
+        @paths_to_cleanup ||= begin
+          paths_to_cleanup = {}
 
           ancestors.reverse.each do |ancestor|
             next unless ancestor.kind_of?(ClassMethods)
-            ancestor.cleanup_method_registry.each_pair do |key, value|
+            ancestor.paths_to_cleanup_registry.each_pair do |key, value|
               if value.nil?
-                cleanup_methods.delete(key)
+                paths_to_cleanup.delete(key)
               else
-                cleanup_methods[key] = value
+                paths_to_cleanup[key] = value
               end
             end
           end
 
-          cleanup_methods
+          paths_to_cleanup
         end
       end
 
-      def reset_cleanup_methods
-        @cleanup_methods = nil
+      # Resets paths_to_cleanup such that it will be recalculated.
+      def reset_paths_to_cleanup
+        @paths_to_cleanup = nil
       end
 
       protected
@@ -48,13 +66,13 @@ module ShellTest
           base.class_dir = Dir.tmpdir
         end
 
-        base.reset_cleanup_methods
-        unless base.instance_variable_defined?(:@cleanup_method_registry)
-          base.instance_variable_set(:@cleanup_method_registry, {})
+        base.reset_paths_to_cleanup
+        unless base.instance_variable_defined?(:@paths_to_cleanup_registry)
+          base.instance_variable_set(:@paths_to_cleanup_registry, {})
         end
 
-        unless base.instance_variable_defined?(:@cleanup_paths)
-          base.instance_variable_set(:@cleanup_paths, ['.'])
+        unless base.instance_variable_defined?(:@default_paths_to_cleanup)
+          base.instance_variable_set(:@default_paths_to_cleanup, ['.'])
         end
 
         unless base.instance_variable_defined?(:@cleanup)
@@ -67,47 +85,65 @@ module ShellTest
         super
       end
 
-      def define_method_cleanup(method_name, dirs)
-        reset_cleanup_methods
-        cleanup_method_registry[method_name.to_sym] = dirs
+      # Define the paths_to_cleanup for the specified method.  The settings
+      # are inherited, but can be overridden in subclasses.
+      def define_paths_to_cleanup(method_name, relative_paths)
+        reset_paths_to_cleanup
+        paths_to_cleanup_registry[method_name.to_sym] = relative_paths
       end
 
-      def remove_method_cleanup(method_name)
-        reset_cleanup_methods
-        cleanup_method_registry.delete(method_name.to_sym)
+      # Remove the paths_to_cleanup for the method as defined on self.  The
+      # paths_to_cleanup inherited from ancestors will still be in effect.
+      def remove_paths_to_cleanup(method_name)
+        reset_paths_to_cleanup
+        paths_to_cleanup_registry.delete(method_name.to_sym)
       end
 
-      def undef_method_cleanup(method_name)
-        reset_cleanup_methods
-        cleanup_method_registry[method_name.to_sym] = nil
+      # Undefines the paths_to_cleanup for the method, preventing inheritance
+      # from ancestors.
+      def undef_paths_to_cleanup(method_name)
+        reset_paths_to_cleanup
+        paths_to_cleanup_registry[method_name.to_sym] = nil
       end
 
-      def cleanup_paths(*dirs)
-        @cleanup_paths = dirs
+      # Sets the default paths_to_cleanup for subsequent methods.
+      def default_paths_to_cleanup(*relative_paths)
+        @default_paths_to_cleanup = relative_paths
       end
 
+      # Mark the methods for cleanup using the default_paths_to_cleanup.  Call
+      # without method names to mark all subsequent methods for cleanup.
       def cleanup(*method_names)
         if method_names.empty?
           @cleanup = true
         else
           method_names.each do |method_name|
-            define_method_cleanup method_name, @cleanup_paths
+            define_paths_to_cleanup method_name, @default_paths_to_cleanup
           end
         end
       end
 
-      def no_cleanup(*method_names)
+      # Prevent cleanup for the methods.  Call without method names to prevent
+      # cleanup for subsequent methods.
+      def do_not_cleanup(*method_names)
         if method_names.empty?
           @cleanup = false
         else
           method_names.each do |method_name|
-            undef_method_cleanup method_name
+            undef_paths_to_cleanup method_name
           end
         end
       end
 
+      # Returns true if the method should be marked for cleanup when added.
+      def mark_for_cleanup?(method_name)
+        @cleanup && !paths_to_cleanup_registry.has_key?(method_name.to_sym) && method_name.to_s.index("test_") == 0
+      end
+
+      # Overridden to ensure methods marked for cleanup are cleaned up.
       def method_added(sym)
-        if @cleanup && !cleanup_method_registry.has_key?(sym.to_sym) && sym.to_s[0, 5] == "test_"
+        super
+        if mark_for_cleanup?(sym)
           cleanup sym
         end
       end
@@ -208,7 +244,7 @@ module ShellTest
     end
 
     # Creates a directory under method_dir.
-    def prepare_dir(relative_path)
+    def setup_dir(relative_path)
       target_dir = path(relative_path)
       unless File.directory?(target_dir)
         FileUtils.mkdir_p(target_dir)
@@ -216,8 +252,10 @@ module ShellTest
       target_dir
     end
 
-    # Same as prepare but does not outdent content.
-    def _prepare(relative_path, content=nil, &block)
+    alias prepare_dir setup_dir
+
+    # Same as setup_file but does not outdent content.
+    def _setup_file(relative_path, content=nil, &block)
       target = path(relative_path)
 
       if File.exists?(target)
@@ -241,16 +279,16 @@ module ShellTest
     # Content provided as a string is outdented (see StringMethods#outdent),
     # so this syntax is possible:
     #
-    #   path = prepare 'file', %{
+    #   path = setup_file 'file', %{
     #     line one
     #     line two
     #   }
     #   File.read(path)  # => "line one\nline two\n"
     #
     # Returns the absolute path to the new file.
-    def prepare(relative_path, content=nil, &block)
+    def setup_file(relative_path, content=nil, &block)
       content = outdent(content) if content
-      _prepare(relative_path, content, &block)
+      _setup_file(relative_path, content, &block)
     end
 
     # Returns the content of the file under method_dir, if it exists.
@@ -272,15 +310,10 @@ module ShellTest
       FileUtils.rm_r(full_path) if File.exists?(full_path)
     end
 
-    # Shortcut to access the class.cleanup_methods.
-    def cleanup_methods
-      self.class.cleanup_methods
-    end
-
-    # Recursively removes paths specified for cleanup in cleanup_methods.
+    # Recursively removes paths specified for cleanup by paths_to_cleanup.
     def cleanup
-      if cleanup_paths = cleanup_methods[method_name.to_sym]
-        cleanup_paths.each {|relative_path| remove(relative_path) }
+      if paths = self.class.paths_to_cleanup[method_name.to_sym]
+        paths.each {|path| remove(path) }
       end
     end
   end

data/lib/shell_test/shell_methods/agent.rb

@@ -20,32 +20,33 @@ module ShellTest
       # 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={})
+      def initialize(master, slave, timer)
         @master = master
         @slave  = slave
         @timer  = timer
-        @prompts = prompts
       end
 
-      def on(prompt, input, timeout=nil)
-        output = expect(prompt, timeout)
+      def on(regexp, input, timeout=nil)
+        output = expect(regexp, 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.
+      # Reads from the slave until the regexp is matched and returns the
+      # resulting string.  If regexp is a String, then it is converted into a
+      # regexp assuming it's a literal prompt (ie /^regexp\z/ - where the
+      # regexp string is Regexp escaped). If regexp is nil 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
+      # will be also be raised if the slave eof is reached before the regexp
       # matches.
-      def expect(prompt, timeout=nil)
-        regexp = prompts[prompt] || prompt
+      def expect(regexp, timeout=nil)
+        if regexp.kind_of?(String)
+          regexp = /#{Regexp.escape(regexp)}\z/
+        end
+
         timer.timeout = timeout
 
         buffer = ''
@@ -66,10 +67,7 @@ module ShellTest
           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.
+            # see notes in Utils#spawn
             c = nil
           end
 

data/lib/shell_test/shell_methods/session.rb

@@ -1,4 +1,3 @@
-require 'shell_test/env_methods'
 require 'shell_test/shell_methods/agent'
 require 'shell_test/shell_methods/utils'
 require 'strscan'
@@ -8,24 +7,15 @@ module ShellTest
 
     # 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
 
@@ -47,18 +37,22 @@ module ShellTest
 
       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
+
+      # The shell PS1, as configured in ENV.
+      def ps1
+        ENV['PS1']
+      end
+
+      # The shell PS2, as configured in ENV.
+      def ps2
+        ENV['PS2']
       end
 
       # Define a step.  At each step:
@@ -99,11 +93,11 @@ module ShellTest
 
       def split(str)
         scanner = StringScanner.new(str)
-        scanner.scan_until(/(#{@prompts[:ps1]})/)
+        scanner.scan_until(/(#{Regexp.escape(ps1)})/)
         scanner.pos -= scanner[1].to_s.length
 
         args = []
-        while output = scanner.scan_until(/(#{@prompts[:ps1]}|#{@prompts[:ps2]}|\{\{(.*?)\}\})/)
+        while output = scanner.scan_until(/(#{Regexp.escape(ps1)}|#{Regexp.escape(ps2)}|\{\{(.*?)\}\})/)
           match = scanner[1]
           input = scanner[2] ? "#{scanner[2]}\n" : scanner.scan_until(/\n/)
 
@@ -115,15 +109,15 @@ module ShellTest
 
           case match
           when ps1
-            prompt = :ps1
+            prompt = match
             if max_run_time == -1
               max_run_time = nil
             end
           when ps2
-            prompt = :ps2
+            prompt = match
           else
             output = output.chomp(match)
-            prompt = /^#{output.split("\n").last}\z/
+            prompt = output.split("\n").last
           end
 
           args << output
@@ -159,7 +153,7 @@ module ShellTest
           args.pop
         else
           args.last << ps1
-          args.concat [:ps1, "exit\n", nil, nil]
+          args.concat [ps1, "exit\n", nil, nil]
         end
 
         while !args.empty?
@@ -178,53 +172,42 @@ module ShellTest
       # 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
+        @log = []
+        @status = super(shell) do |master, slave|
+          agent = Agent.new(master, slave, timer)
+          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
 
-            begin
-              yield agent
-            rescue Agent::ReadError
-              log << $!.buffer
-              $!.message << "\n#{summary}"
-              raise
-            end
+            log.clear
+          end
 
-            timer.stop
-            agent.close
+          begin
+            yield agent
+          rescue Agent::ReadError
+            log << $!.buffer
+            $!.message << "\n#{summary}"
+            raise
           end
+
+          timer.stop
+          agent.close
         end
         self
       end

data/lib/shell_test/shell_methods/utils.rb

@@ -14,40 +14,74 @@ module ShellTest
       # 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)
+      def spawn(cmd, log=[])
+        # The race condition described above actually applies to both kill and
+        # wait which raise Errno::ESRCH or Errno::ECHILD if they lose the
+        # race.  This code is designed to capture those errors if they occur
+        # and then give the cleanup thread a chance to take over; eventually
+        # it will raise a ChildExited error.  This is a sketchy use of
+        # exceptions for flow control but there is little option - a
+        # consequence of PTY using threads with side effects.
         PTY.spawn(cmd) do |slave, master, pid|
           begin
             yield(master, slave)
-            Process.wait(pid)
+
+            begin
+              Process.wait(pid)
+            rescue Errno::ECHILD
+              Thread.pass
+              raise
+            end
 
           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.
+            # This is the 'normal' exit route on 1.8.6 and 1.8.7.
             return $!.status
 
-          rescue Exception
-            # cleanup the pty on error
-            Process.kill(9, pid)
+          rescue Exception => error
+            begin
 
-            # clearing the slave allows the wait to complete faster
-            while IO.select([slave],nil,nil,0.1)
+              # Manually cleanup the pid on error.  This code no longer cares
+              # what exactly happens to $? - the point is to make sure the
+              # child doesn't become a zombie and then re-raise the error.
               begin
-                break unless slave.read(1)
-              rescue Errno::EIO
-                break
+                Process.kill(9, pid)
+              rescue Errno::ESRCH
+                Thread.pass
+                raise
               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
+              # Clearing the slave allows quicker exits on OS X.
+              while IO.select([slave],nil,nil,0.1)
+                begin
+                  break unless 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.
+                  break
+                end
+              end
 
-            raise
+              begin
+                Process.wait(pid)
+              rescue Errno::ECHILD
+                Thread.pass
+                raise
+              end
+
+            rescue PTY::ChildExited
+              # The cleanup thread could finish at any point in the rescue
+              # handling so account for that here.
+            ensure
+              raise error
+            end
           end
         end
 
         $?
       end
+
     end
   end
 end

data/lib/shell_test/shell_methods.rb

@@ -1,3 +1,4 @@
+require 'shell_test/env_methods'
 require 'shell_test/regexp_escape'
 require 'shell_test/string_methods'
 require 'shell_test/shell_methods/session'
@@ -7,6 +8,18 @@ module ShellTest
     include StringMethods
     include EnvMethods
 
+    attr_reader :original_env
+
+    def setup
+      super
+      @original_env = set_env('PS1' => '$ ', 'PS2' => '> ')
+    end
+
+    def teardown
+      set_env(@original_env)
+      super
+    end
+
     def pty(script, options={}, &block)
       _pty outdent(script), options, &block
     end

data/lib/shell_test/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: shell_test
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 15
   prerelease: 
   segments: 
   - 0
-  - 3
+  - 4
   - 0
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-23 00:00:00 -06:00
+date: 2011-11-01 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
@@ -48,7 +48,7 @@ files:
 - README.rdoc
 - MIT-LICENSE
 has_rdoc: true
-homepage: ""
+homepage: http://github.com/thinkerbot/shell_test
 licenses: 
 - MIT
 post_install_message: