dia 2.0.0 → 2.0.1

data/lib/dia/shared_features.rb

@@ -1,24 +1,29 @@
 module Dia
 
+
+  # The SharedFeatures module implements methods which are shared by 
+  # {Dia::Application Dia::Application} and {Dia::RubyBlock Dia::RubyBlock}.  
+  # This module shoudln't be interacted with directly. 
   module SharedFeatures
-    
-    # @return  [Fixnum, nil]  Returns the Process ID(PID) of the last child process that was
-    #                         used to execute a sandbox.  
-    #                         Returns nil if #run or #run_nonblock has not been called yet.
+   
+    attr_reader :pid
+
+    # @return  [Fixnum]       Returns the Process ID(PID) of the last child process to execute a
+    #                         a sandbox.
+    #
+    # @return  [nil]          Returns nil if #run or #run_nonblock have not been called.
     def pid
       @pid
     end
   
-    # The exit_status method will return the exit status of your sandbox.  
-    # This method *will* block until the child process(your sandbox) exits
-    # when being used with #run_nonblock.
+    # The exit_status method will return the exit status of the child process 
+    # used to execute a sandbox.      
+    # This method blocks until the spawned process exits when being used with #run_nonblock.
+    #
+    # @return [Fixnum]      Returns the exit status as a Fixnum. 
+    #
+    # @return [nil]         Returns nil if #run or #run_nonblock have not been called.
     #
-    # @return [Fixnum, nil] Returns the exit status of your sandbox as a 
-    #                       Fixnum.  
-    #                       Returns nil if #run or #run_nonblock has not
-    #                       been called yet.  
-    #                       Returns nil if the process hasn't exited yet and 
-    #                       #run is being used.
     # @since 1.5
     def exit_status()
       unless @exit_status.nil?
@@ -27,22 +32,14 @@ module Dia
       end
     end
 
-    # The terminate method will send the SIGKILL signal to your sandbox.
-    #
-    # To prevent the possible accumulation of zombies, this method will 
-    # wait to collect the exit status of your sandbox if it doesn't appear 
-    # to have left the process table after sending SIGKILL.
+    # The terminate method will terminate the child process executing a sandbox.
     #
-    # This is a rare event, and when it does happen #terminate shouldn't block
-    # for more than one second.
+    # @raise  [SystemCallError] It could raise a number of subclasses of SystemCallError
+    #                           if a signal could not be sent to the child process.
     #
-    # @raise  [SystemCallError] It may raise a number of subclasses of 
-    #                           SystemCallError if a call to Process.kill 
-    #                           was unsuccessful
+    # @return [Fixnum]          Returns 1 when successful.
     #
-    # @return [Fixnum, nil]     Returns 1 when successful.     
-    #                           Returns nil if #run or #run_nonblock has not 
-    #                           been called yet. 
+    # @return [nil]             Returns nil if #run or #run_nonblock has not been called. 
     def terminate()
       ret = Process.kill('SIGKILL', @pid) unless @pid.nil?
       # precaution against the collection of zombie processes.
@@ -50,15 +47,17 @@ module Dia
       ret
     end
     
-    # This method will tell you if your sandbox is still running by returning a boolean.
+    # This method can tell you whether the child process used to execute your sandbox is 
+    # running or not.
+    #
+    # @raise  [SystemCallError] It could raise a number of subclasses of SystemCallError
+    #                           if a signal could not be sent to the child process.
+    #
+    # @return [true]            Returns true when the child process is running.
     #
-    # @raise  [SystemCallError] It may raise a number of subclasses of SystemCallError 
-    #                           if a signal cannot be sent to the process running 
-    #                           a sandbox.
+    # @return [false]           Returns false when the child process is not running.
     #
-    # @return [Boolean,nil]     Returns true, false, or nil.  
-    #                           Returns nil if #run or #run_nonblock has 
-    #                           not been called yet.
+    # @return [nil]             Returns nil if #run or #run_nonblock have not been called.
     def running?()
       if @pid.nil?
         nil

data/test/suite/lib/dia/Application#initialize.rb

@@ -0,0 +1,21 @@
+suite('Application') do
+  suite('#initialize') do
+    suite('Raises') do
+    
+      exercise("When the Dia::Profiles::NO_OS_SERVICES profile is supplied to #initialize.") do
+        begin
+          dia = Dia::Application.new(Dia::Profiles::NO_OS_SERVICES, "touch /tmp/bar") 
+        rescue ArgumentError => e
+          @result = true
+        else
+          @result = false
+        end
+      end
+
+      verify('#initialize will raise an ArgumentError.') do
+        @result
+      end
+
+    end
+  end
+end

data/test/suite/lib/dia/Application#run.rb

@@ -0,0 +1,16 @@
+suite('Application') do
+  suite('#run') do
+    suite('Return values') do
+
+      exercise('When #run has finished executing.') do
+        dia = Dia::Application.new(Dia::Profiles::NO_INTERNET, "touch /tmp/bar")
+        @result = dia.run
+      end
+
+      verify('It returns the Process ID of the spawned process.') do
+        @result.class == Fixnum
+      end
+
+    end
+  end
+end

data/test/suite/lib/dia/Application#run_nonblock.rb

@@ -0,0 +1,16 @@
+suite('Application') do
+  suite('#run_nonblock') do
+    suite('Return values') do
+
+      exercise('When #run_nonblock has finished executing.') do
+        dia = Dia::Application.new(Dia::Profiles::NO_INTERNET, "touch /tmp/bar")
+        @result = dia.run
+      end
+
+      verify('It returns the Process ID of the spawned process.') do
+        @result.class == Fixnum
+      end
+
+    end
+  end
+end

data/test/suite/lib/dia/RubyBlock#exception.rb

@@ -0,0 +1,46 @@
+suite('RubyBlock') do
+  suite('#exception') do
+    suite('Return values') do
+      
+      exercise('When exceptions are being captured, and an exception is raised.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          raise(StandardError, "raised")
+        end
+
+        dia.rescue_exception = true
+        dia.run
+        @result = dia.exception
+      end
+
+      verify('#exception returns a Dia::ExceptionStruct object.') do
+        @result.class == Dia::ExceptionStruct
+      end
+
+      exercise('When exceptions are being captured, and no exception is raised.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.rescue_exception = true
+        dia.run
+        @result = dia.exception
+      end
+
+      verify('#exception returns nil as no exception is available.') do
+        @result == nil
+      end
+
+      exercise('When exceptions are not being captured, and an exception is raised.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          raise(StandardError, "raised")
+        end
+        dia.redirect_stderr  = true  # I don't want the test output to be flooded with a backtrace.
+        dia.rescue_exception = false # default, but lets be explicit.
+        dia.run
+        @result = dia.exception
+      end
+
+      verify('#exception returns nil.') do
+        @result == nil
+      end
+
+    end
+  end
+end

data/test/suite/lib/dia/RubyBlock#exception_raised?.rb

@@ -0,0 +1,45 @@
+suite('RubyBlock') do
+  suite('#exception_raised?') do
+    suite('Return values') do
+   
+      exercise('When an exception has been raised.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          raise(StandardError, "raised") 
+        end
+        dia.rescue_exception = true
+        dia.run
+        @result = dia.exception_raised?
+      end
+
+      verify('#exception_raised? returns true.') do
+        @result == true
+      end
+
+      exercise('When an exception has not been raised.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.rescue_exception = true
+        dia.run
+        @result = dia.exception_raised?
+      end
+
+      verify('#exception_raised? returns false.') do
+        @result == false
+      end
+
+      exercise('When exceptions are not being captured, and an exception has been raised.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          raise(StandardError, "raised")
+        end
+        dia.rescue_exception = false # default, but lets be explicit.
+        dia.redirect_stderr = true   # I don't want the tests to be flooded with a backtrace.
+        dia.run
+        @result = dia.exception_raised?
+      end
+
+      verify('#exception_raised? returns false') do
+        @result == false
+      end
+
+    end
+  end
+end

data/test/suite/lib/dia/RubyBlock#redirect_stderr?.rb

@@ -0,0 +1,27 @@
+suite('RubyBlock') do  
+  suite('#redirect_stderr?') do
+    suite('Return values') do
+  
+      exercise('When stderr output is being redirected.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.redirect_stderr = true
+        @result = dia.redirect_stderr?
+      end
+
+      verify('#redirect_stderr? returns true.') do
+        @result == true
+      end
+
+      exercise('When stderr output is not being redirected.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.redirect_stderr = false
+        @result = dia.redirect_stderr?
+      end
+
+      verify('#redirect_stderr? returns false.') do
+        @result == false
+      end
+
+    end
+  end
+end

data/test/suite/lib/dia/RubyBlock#redirect_stdout?.rb

@@ -0,0 +1,27 @@
+suite('RubyBlock') do  
+  suite('#redirect_stdout?') do
+    suite('Return values') do
+
+      exercise('When stdout is being redirected.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.redirect_stdout = true
+        @result = dia.redirect_stdout?
+      end
+
+      verify('#redirect_stdout? returns true.') do
+        @result == true
+      end
+
+      exercise('When stdout is not being redirected.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.redirect_stdout = false
+        @result = dia.redirect_stdout?
+      end
+
+      verify('#redirect_stdout? returns false.') do
+        @result == false
+      end
+    
+    end
+  end
+end

data/test/suite/lib/dia/RubyBlock#rescue_exception?.rb

@@ -0,0 +1,28 @@
+suite('RubyBlock') do
+  suite('#rescue_exception?') do
+    suite('Return values') do 
+
+      exercise('When exceptions are being captured.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.rescue_exception = true
+        @result = dia.rescue_exception?
+      end
+
+      verify('#rescue_exception? returns true') do
+        @result == true
+      end
+
+      exercise('When exceptions are not being captured.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        dia.rescue_exception = false # default, but lets be explicit.
+        @result = dia.rescue_exception?
+      end
+
+      verify('#rescue_exception? returns false') do
+        @result == false
+      end
+
+    end
+  end
+end
+

data/test/suite/lib/dia/RubyBlock#run.rb

@@ -0,0 +1,135 @@
+suite('RubyBlock') do
+  suite('#run') do
+    suite('Return values') do
+
+      exercise('When #run has finished executing.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
+        @result = dia.run
+      end
+
+      verify('It returns the Process ID of the spawned process.') do
+        @result.class == Fixnum
+      end
+
+    end
+    
+    suite('Behavior') do
+
+      setup do
+        @result          = nil
+        @reader, @writer = IO.pipe
+      end
+
+      exercise('Confirm the profile ' \
+               'Dia::Profiles::NO_INTERNET ' \
+               'is creating a working sandbox environment.') do      
+        sandbox = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          begin
+            @reader.close
+            TCPSocket.open('http://www.google.com', 80)
+            @writer.write('false')
+          rescue SocketError, SystemCallError => e
+            @writer.write('true')
+          ensure
+            @writer.close
+          end
+        end
+
+        sandbox.run
+        
+        @writer.close
+        @result = @reader.gets
+        @reader.close
+      end
+
+      verify(nil) do
+        @result == 'true'
+      end
+
+      exercise('Confirm the profile ' \
+               'Dia::Profiles::NO_FILESYSTEM_WRITE ' \
+               'is creating a working sandbox environment.') do
+        
+        sandbox = Dia::RubyBlock.new(Dia::Profiles::NO_FILESYSTEM_WRITE) do
+          begin
+            @reader.close
+            File.open('/tmp/foo.txt', 'w') { |f| f.puts('fail') }
+            @writer.write('false')
+          rescue SocketError, SystemCallError => e
+            @writer.write('true')
+          ensure 
+            @writer.close
+          end
+        end
+        
+
+        sandbox.run
+
+        @writer.close
+        @result = @reader.gets
+        @reader.close
+      end
+
+      verify(nil) do
+        @result == 'true'
+      end
+
+      exercise('Confirm the profile ' \
+               'Dia::Profiles::NO_FILESYSTEM_WRITE_EXCEPT_TMP ' \
+               'is creating a working sandbox environment. ') do      
+        sandbox = Dia::RubyBlock.new(Dia::Profiles::NO_FILESYSTEM_WRITE_EXCEPT_TMP) do
+          begin
+            @reader.close
+            out = Time.now.to_s
+            File.open('/tmp/%s.dia_test' % [ out ] , 'w') { |f| f.puts('success') }
+            File.open(File.join(ENV['HOME'], 'fail.txt')) { |f| f.puts('fail') }
+            @writer.write('false')
+          rescue SocketError, SystemCallError => e
+            if File.exists?('/tmp/%s.dia_test' % [ out ])
+              @writer.write('true')
+            else
+              @writer.write('false')
+            end
+          ensure 
+            @writer.close
+          end
+        end
+        
+        sandbox.run
+
+        @writer.close
+        @result = @reader.gets
+        @reader.close
+      end
+
+      verify(nil) do
+        @result == 'true'
+      end
+
+      exercise('Confirm the profile ' \
+               'Dia::Profiles::NO_NETWORKING ' \
+               'is creating a working sandbox environment') do
+        sandbox = Dia::RubyBlock.new(Dia::Profiles::NO_NETWORKING) do  
+          begin
+            @reader.close
+            TCPSocket.open('http://www.youtube.com', 80)
+            @writer.write('false')
+          rescue SocketError => e
+            @writer.write('true')
+          end
+        end
+        
+        sandbox.run
+        
+        @writer.close
+        @result = @reader.gets
+        @reader.close    
+      end
+
+      verify(nil) do
+        @result == 'true'
+      end
+
+    end    
+  end
+end