scmd 2.3.1 → 3.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 67125e428f1adb1fe7f302c3d0276a0384d5b41a74be0a40b52256043dc22632
+  data.tar.gz: c1dcc9b7152046ff0a5af224acc3c31f3124c423e818d048f8879310d2b9d645
+SHA512:
+  metadata.gz: 74b33660ba6eab558d637797e1e03ec67607a0110be680822a22851fa7068d14b60a4d8f2fb1ff58ad1867f1c964bd34c619838efa7187c775eb491b6cef04c3
+  data.tar.gz: 17ea7892c22832d00868a8b9659ba8aabfc57b1c0c3df0a91e41a929d47af039ac40110b3a3b58a3688e09db61a42a531b68903a23f0ec4c8e978bec8deb3002

data/Gemfile

@@ -1,11 +1,11 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 gemspec
 
-gem 'rake'
-gem 'pry', "~> 0.9.0"
-gem 'whysoslow'
+gem "pry"
+gem "whysoslow"
 
-platform :rbx do
-  gem 'rubysl'
-end
+# to release, uncomment this and run `bundle exec ggem r -f`
+gem 'ggem'

data/README.md

@@ -42,7 +42,7 @@ cmd.start
 
 begin
   cmd.wait(10)
-rescue Scmd::Timeout => err
+rescue Scmd::TimeoutError => err
   cmd.stop # attempt to stop the cmd nicely, kill if doesn't stop in time
   cmd.kill # just kill the cmd now
 end
@@ -94,6 +94,98 @@ Raise an exception if not successful with `run!`:
 Scmd.new("cd /path/that/does/not/exist").run! #=> Scmd::Command::Failure
 ```
 
+### Environment variables
+
+Pass environment variables:
+
+```ruby
+cmd = Scmd.new("echo $TEST_VAR", {
+  :env => {
+    'TEST_VAR' => 'hi'
+  }
+})
+```
+
+### Process spawn options
+
+Pass options:
+
+```ruby
+reader, writer = IO.pipe
+# this is an example that uses file descriptor redirection options
+cmd = Scmd.new("echo test 1>&#{writer.fileno}", {
+  :options => { writer => writer }
+})
+reader.gets # => "test\n"
+```
+
+For all the possible options see [posix-spawn](https://github.com/rtomayko/posix-spawn#status).
+
+## Testing
+
+Scmd comes with some testing utilities built in.  Specifically this includes a command spy and a "test mode" API on the main `Scmd` namespace.
+
+### Command Spy
+
+```ruby
+require 'scmd/command_spy'
+spy = Scmd::CommandSpy.new(cmd_str)
+spy.exitstatus = 1
+spy.stdout = 'some test output'
+Assert.stub(Scmd, :new).with(cmd_str){ spy }
+
+cmd = Scmd.new(cmd_str) # => spy
+cmd.run('some input')
+
+cmd.run_called?           # => true
+cmd.run_calls.size        # => 1
+cmd.run_calls.first.input # => 'some input'
+```
+
+The spy is useful for stubbing out system commands that you don't want to call or aren't safe to call in the test suite.  It responds to the same API that commands do but doesn't run any system commands.
+
+### "Test Mode" API
+
+```ruby
+Scmd.add_command(cmd_str){ |cmd| cmd.stdout = 'some output' } # => raises NoMethodError
+
+ENV['SCMD_TEST_MODE'] = '1'
+Scmd.add_command(cmd_str){ |cmd| cmd.stdout = 'some output' }
+Scmd.add_command(cmd_str).with({:env => { :SOME_ENV_VAR => '1' }}) do |cmd|
+  cmd.stdout = 'some other output'
+end
+Scmd.commands.empty? # => false
+
+cmd = Scmd.new(cmd_str)
+cmd.class                 # => Scmd::CommandSpy
+cmd.stdout                # => 'some output'
+cmd.run('some input')
+Scmd.calls.size           # => 1
+Scmd.calls.last.class     # => Scmd::Call
+Scmd.calls.last.cmd_str   # => cmd_str
+Scmd.calls.last.input     # => 'some input'
+Scmd.calls.last.cmd.class # => Scmd::CommandSpy
+
+cmd = Scmd.new(cmd_str, {:env => { 'SOME_ENV_VAR' => '1' }})
+cmd.class                 # => Scmd::CommandSpy
+cmd.stdout                # => 'some other output'
+cmd.run('some input')
+Scmd.calls.size           # => 2
+Scmd.calls.last.class     # => Scmd::Call
+Scmd.calls.last.cmd_str   # => cmd_str
+Scmd.calls.last.input     # => 'some input'
+Scmd.calls.last.cmd.class # => Scmd::CommandSpy
+Scmd.calls.last.cmd.env   # => { 'SOME_ENV_VAR' => '1' }
+
+Scmd.reset
+Scmd.commands.empty? # => true
+Scmd.calls.empty?    # => true
+```
+
+Use these singleton methods on the `Scmd` namespace to add specific command spies in specific contexts and to track command calls (runs, starts).  Use `reset` to reset the state of things.
+
+**Note:** these methods are only available when test mode is enabled (when the `SCMD_TEST_MODE` env var has a non-falsey value).  Otherwise these methods will raise `NoMethodError`.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/bench/results.txt

@@ -2,79 +2,79 @@ echo hi: 1 times
 ----------------
 whysoslow? ..
 
-mem @ start             29 MB                   ??
-mem @ finish            29 MB                   +   0 MB,   0%
+mem @ start             17 MB                   ??
+mem @ finish            17 MB                   +   0 MB,   0%
 
-         user     system   total    real
-time     0.0 ms   0.0 ms   0.0 ms   1.928 ms
+                      user                  system                total                 real
+time                  0.5820000000000001 ms 0.5519999999999999 ms 3.786 ms              3.7030000000000003 ms
 
 echo hi: 10 times
 -----------------
 whysoslow? ..
 
-mem @ start             38 MB                   ??
-mem @ finish            38 MB                   -   0 MB,   0%
+mem @ start             17 MB                   ??
+mem @ finish            17 MB                   +   0 MB,   0%
 
-          user      system    total     real
-time      0.0 ms    0.0 ms    10.0 ms   16.874 ms
+                      user                  system                total                 real
+time                  2.475 ms              3.822 ms              32.675999999999995 ms 34.702 ms
 
 echo hi: 100 times
 ------------------
 whysoslow? ..
 
-mem @ start             38 MB                   ??
-mem @ finish            38 MB                   -   0 MB,   0%
+mem @ start             17 MB                   ??
+mem @ finish            18 MB                   +   0 MB,   2%
 
-           user       system     total      real
-time       20.0 ms    20.0 ms    130.0 ms   147.925 ms
+                      user                  system                total                 real
+time                  19.75 ms              31.77 ms              281.766 ms            306.74899999999997 ms
 
 echo hi: 1000 times
 -------------------
 whysoslow? ..
 
-mem @ start             38 MB                   ??
-mem @ finish            41 MB                   +   3 MB,   7%
+mem @ start             18 MB                   ??
+mem @ finish            29 MB                   +  11 MB,  61%
 
-            user        system      total       real
-time        170.0 ms    180.0 ms    1320.0 ms   1390.406 ms
+                      user                  system                total                 real
+time                  161.98399999999998 ms 271.296 ms            2432.76 ms            2662.98 ms
 
 cat test/support/bigger-than-64k.txt: 1 times
 ---------------------------------------------
 whysoslow? ..
 
-mem @ start             41 MB                   ??
-mem @ finish            41 MB                   -   0 MB,   0%
+mem @ start             31 MB                   ??
+mem @ finish            31 MB                   +   0 MB,   1%
 
-         user     system   total    real
-time     0.0 ms   0.0 ms   0.0 ms   3.487 ms
+                     user                 system               total                real
+time                 0.412 ms             0.504 ms             4.343999999999999 ms 4.654 ms
 
 cat test/support/bigger-than-64k.txt: 10 times
 ----------------------------------------------
 whysoslow? ..
 
-mem @ start             41 MB                   ??
-mem @ finish            43 MB                   +   2 MB,   4%
+mem @ start             31 MB                   ??
+mem @ finish            34 MB                   +   2 MB,   7%
 
-          user      system    total     real
-time      0.0 ms    0.0 ms    20.0 ms   30.533 ms
+                      user                  system                total                 real
+time                  3.2880000000000003 ms 4.386 ms              43.447 ms             46.552 ms
 
 cat test/support/bigger-than-64k.txt: 100 times
 -----------------------------------------------
 whysoslow? ..
 
-mem @ start             43 MB                   ??
-mem @ finish            85 MB                   +  42 MB,  98%
+mem @ start             33 MB                   ??
+mem @ finish            56 MB                   +  23 MB,  68%
 
-          user      system    total     real
-time      40.0 ms   40.0 ms   250.0 ms  274.06 ms
+                      user                  system                total                 real
+time                  28.892999999999997 ms 40.599000000000004 ms 407.804 ms            440.11 ms
 
 cat test/support/bigger-than-64k.txt: 1000 times
 ------------------------------------------------
 whysoslow? ..
 
-mem @ start             85 MB                   ??
-mem @ finish            506 MB                  + 421 MB, 497%
+mem @ start             44 MB                   ??
+mem @ finish            297 MB                  + 254 MB, 582%
 
-            user        system      total       real
-time        360.0 ms    400.0 ms    2540.0 ms   2649.686 ms
+                     user                 system               total                real
+time                 285.236 ms           408.677 ms           4097.647 ms          4428.276999999999 ms
 

data/bench/runner.rb

@@ -1,12 +1,13 @@
-require 'whysoslow'
-require 'scmd'
+# frozen_string_literal: true
 
-class ScmdBenchRunner
+require "whysoslow"
+require "scmd"
 
+class ScmdBenchRunner
   attr_reader :result
 
   def self.run(*args)
-    self.new(*args).run
+    new(*args).run
   end
 
   def initialize(printer_io, cmd, num_times = 10)
@@ -15,15 +16,16 @@ class ScmdBenchRunner
       num_times.times{ cmd.run! }
     end
 
-    @printer = Whysoslow::DefaultPrinter.new(printer_io, {
-      :title => "#{@cmd.cmd_str}: #{num_times} times",
-      :verbose => true
-    })
+    @printer =
+      Whysoslow::DefaultPrinter.new(
+        printer_io,
+        title: "#{@cmd.cmd_str}: #{num_times} times",
+        verbose: true,
+      )
     @runner = Whysoslow::Runner.new(@printer)
   end
 
   def run
-    @runner.run &@proc
+    @runner.run(&@proc)
   end
-
 end

data/lib/scmd.rb

@@ -1,10 +1,49 @@
-require 'scmd/version'
-require 'scmd/command'
+# frozen_string_literal: true
+
+require "scmd/version"
+require "scmd/command"
 
 module Scmd
+  # Scmd can be run in "test mode".  This means that command spies will be used
+  # in place of "live" commands, each time a command is run or started will be
+  # logged in a collection and option-specific spies can be added and used to
+  # "stub" spies with specific attributes in specific contexts.
+
+  def self.new(*args)
+    if !ENV["SCMD_TEST_MODE"]
+      Command.new(*args)
+    else
+      commands.get(*args)
+    end
+  end
 
-  def self.new(*args, &block)
-    Command.new(*args, &block)
+  def self.commands
+    raise NoMethodError unless ENV["SCMD_TEST_MODE"]
+    @commands ||= begin
+      require "scmd/stored_commands"
+      StoredCommands.new
+    end
+  end
+
+  def self.calls
+    raise NoMethodError unless ENV["SCMD_TEST_MODE"]
+    @calls ||= []
+  end
+
+  def self.reset
+    raise NoMethodError unless ENV["SCMD_TEST_MODE"]
+    calls.clear
+    commands.remove_all
+  end
+
+  def self.add_command(cmd_str, &block)
+    commands.add(cmd_str, &block)
+  end
+
+  class Call < Struct.new(:cmd_str, :input, :cmd)
+    def initialize(cmd_spy, input)
+      super(cmd_spy.cmd_str, input, cmd_spy)
+    end
   end
 
   TimeoutError = Class.new(::RuntimeError)
@@ -15,5 +54,4 @@ module Scmd
       set_backtrace(called_from || caller)
     end
   end
-
 end

data/lib/scmd/command.rb

@@ -1,6 +1,8 @@
-require 'thread'
-require 'posix-spawn'
-require 'scmd'
+# frozen_string_literal: true
+
+require "thread"
+require "posix-spawn"
+require "scmd"
 
 # Scmd::Command is a base wrapper for handling system commands. Initialize it
 # with with a string specifying the command to execute.  You can then run the
@@ -8,23 +10,28 @@ require 'scmd'
 # create a more custom command wrapper.
 
 module Scmd
-
   class Command
     READ_SIZE            = 10240 # bytes
     READ_CHECK_TIMEOUT   = 0.001 # seconds
     DEFAULT_STOP_TIMEOUT = 3     # seconds
 
-    attr_reader :cmd_str, :env
+    attr_reader :cmd_str, :env, :options
     attr_reader :pid, :exitstatus, :stdout, :stderr
 
-    def initialize(cmd_str, env = nil)
+    def initialize(cmd_str, opts = nil)
+      opts ||= {}
       @cmd_str = cmd_str
-      @env     = stringify_hash(env || {})
+      @env     = stringify_hash(opts[:env] || {})
+      @options = opts[:options] || {}
       reset_attrs
     end
 
     def run(input = nil)
-      run!(input) rescue RunError
+      begin
+        run!(input)
+      rescue
+        RunError
+      end
       self
     end
 
@@ -32,11 +39,13 @@ module Scmd
       start_err_msg, start_err_bt = nil, nil
       begin
         start(input)
-      rescue StandardError => err
-        start_err_msg, start_err_bt = err.message, err.backtrace
+      rescue => ex
+        start_err_msg, start_err_bt = ex.message, ex.backtrace
       ensure
         wait # indefinitely until cmd is done running
-        raise RunError.new(start_err_msg || @stderr, start_err_bt || caller) if !success?
+        unless success?
+          raise RunError.new(start_err_msg || @stderr, start_err_bt || caller)
+        end
       end
 
       self
@@ -51,15 +60,15 @@ module Scmd
         while @child_process.check_for_exit
           begin
             read_output
-          rescue EOFError => err
+          rescue EOFError # rubocop:disable Lint/SuppressedException
           end
         end
-        @stop_w.write_nonblock('.')
+        @stop_w.write_nonblock(".")
       end
     end
 
     def wait(timeout = nil)
-      return if !running?
+      return unless running?
 
       wait_for_exit(timeout)
       if @child_process.running?
@@ -76,20 +85,20 @@ module Scmd
     end
 
     def stop(timeout = nil)
-      return if !running?
+      return unless running?
 
       send_term
       begin
         wait(timeout || DEFAULT_STOP_TIMEOUT)
-      rescue TimeoutError => err
+      rescue TimeoutError
         kill
       end
     end
 
-    def kill(sig = nil)
-      return if !running?
+    def kill(signal = nil)
+      return unless running?
 
-      send_kill(sig)
+      send_kill(signal)
       wait # indefinitely until cmd is killed
     end
 
@@ -106,32 +115,35 @@ module Scmd
     end
 
     def inspect
-      reference = '0x0%x' % (self.object_id << 1)
+      reference = "0x0%x" % (object_id << 1)
       "#<#{self.class}:#{reference}"\
-      " @cmd_str=#{self.cmd_str.inspect}"\
+      " @cmd_str=#{cmd_str.inspect}"\
       " @exitstatus=#{@exitstatus.inspect}>"
     end
 
     private
 
     def read_output
-      @child_process.read(READ_SIZE){ |out, err| @stdout += out; @stderr += err }
+      @child_process.read(READ_SIZE) do |out, err|
+        @stdout += out
+        @stderr += err
+      end
     end
 
     def wait_for_exit(timeout)
-      ios, _, _ = IO.select([ @stop_r ], nil, nil, timeout)
-      @stop_r.read_nonblock(1) if ios && ios.include?(@stop_r)
+      ios, _, _ = IO.select([@stop_r], nil, nil, timeout)
+      @stop_r.read_nonblock(1) if ios&.include?(@stop_r)
     end
 
     def reset_attrs
-      @stdout, @stderr, @pid, @exitstatus = '', '', nil, nil
+      @stdout, @stderr, @pid, @exitstatus = +"", +"", nil, nil
     end
 
     def setup_run
       reset_attrs
       @stop_r, @stop_w = IO.pipe
       @read_output_thread = nil
-      @child_process = ChildProcess.new(@cmd_str, @env)
+      @child_process = ChildProcess.new(@cmd_str, @env, @options)
     end
 
     def teardown_run
@@ -143,15 +155,15 @@ module Scmd
     end
 
     def send_term
-      send_signal 'TERM'
+      send_signal "TERM"
     end
 
-    def send_kill(sig = nil)
-      send_signal(sig || 'KILL')
+    def send_kill(signal = nil)
+      send_signal(signal || "KILL")
     end
 
     def send_signal(sig)
-      return if !running?
+      return unless running?
       @child_process.send_signal(sig)
     end
 
@@ -162,11 +174,14 @@ module Scmd
     end
 
     class ChildProcess
-
       attr_reader :pid, :stdin, :stdout, :stderr
 
-      def initialize(cmd_str, env)
-        @pid, @stdin, @stdout, @stderr = *::POSIX::Spawn::popen4(env, cmd_str)
+      def initialize(cmd_str, env, options)
+        @pid, @stdin, @stdout, @stderr = *::POSIX::Spawn.popen4(
+          env,
+          cmd_str,
+          options,
+        )
         @wait_pid, @wait_status = nil, nil
       end
 
@@ -188,25 +203,34 @@ module Scmd
       end
 
       def write(input)
-        if !input.nil?
+        unless input.nil?
           [*input].each{ |line| @stdin.puts line.to_s }
           @stdin.close
         end
       end
 
       def read(size)
-        ios, _, _ = IO.select([ @stdout, @stderr ], nil, nil, READ_CHECK_TIMEOUT)
+        ios, _, _ =
+          IO.select([@stdout, @stderr], nil, nil, READ_CHECK_TIMEOUT)
         if ios && block_given?
-          yield read_if_ready(ios, @stdout, size), read_if_ready(ios, @stderr, size)
+          yield(
+            read_if_ready(ios, @stdout, size),
+            read_if_ready(ios, @stderr, size)
+          )
         end
       end
 
       def send_signal(sig)
-        process_kill(sig, self.pid)
+        process_kill(sig, pid)
       end
 
-      def flush_stdout; @stdout.read; end
-      def flush_stderr; @stderr.read; end
+      def flush_stdout
+        @stdout.read
+      end
+
+      def flush_stderr
+        @stderr.read
+      end
 
       def teardown
         [@stdin, @stdout, @stderr].each{ |fd| fd.close if fd && !fd.closed? }
@@ -215,7 +239,7 @@ module Scmd
       private
 
       def read_if_ready(ready_ios, io, size)
-        ready_ios.include?(io) ? read_by_size(io, size) : ''
+        ready_ios.include?(io) ? read_by_size(io, size) : ""
       end
 
       def read_by_size(io, size)
@@ -232,11 +256,8 @@ module Scmd
       end
 
       def pgrep
-        @pgrep ||= Command.new('which pgrep').run.stdout.strip
+        @pgrep ||= Command.new("which pgrep").run.stdout.strip
       end
-
     end
-
   end
-
 end