shell_mock 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0774052a9e5d9c22ec4c25344e620d68cddc8604
-  data.tar.gz: 76f022bcb48ff0558e5f4e4564a9a0ff63ddc30c
+  metadata.gz: b756c372c9477ca0a21a3894fb4d07c35e87c14e
+  data.tar.gz: 565cb68f40d84a3f2d97ccaa50cad9aa41f16eb1
 SHA512:
-  metadata.gz: 5ce25833d01a646e100d285ce32f9810e15f348d760db2dacd669c8f045c600a16475026429226d6e10b7086c79485bfe73b0c48e2217bc272960c8eea6c479b
-  data.tar.gz: 1f0547eb74bbfd0296a5ad37e07b66eb15ce5f516ff78ad2c2f1abb4acbe792d4fb51a3d3c5614b294a8d164cf0c7ca8066ce8a128ac10078c6fa1fba494bd46
+  metadata.gz: 40cf06dcafcc3e976cedac4a59623a1d47fc4c4f90f437a149d90f26ef62a3b200b6a342273bdd96036070107fa031d234a34a6fc56b457c9b0be99645257383
+  data.tar.gz: 9cdd1c5d0e1a1d8630aa03506493b2e847ad142fe47b4a56bfd5623522b1e8268369e045ea55fa9518f596b77a002730d3e50b5dc4e1d7597848b4a5e87baf5c

data/CHANGELOG.md

@@ -1,12 +1,20 @@
 ## ROADMAP 1.0.0
 
-* add `CommandStub#with_side_effect(&blk)` for specifying desired side effects
-* add `CommandStub#with_stdout(str)` & `CommandStub#with_stderr(str)`. these will work differently for backtick than it will for system & exec.
+* convert `CommandStub#and_exit` to `CommandStub#will_exit`
+* convert `CommandStub#and_output` to `CommandStub#will_output`
+* convert `CommandStub#and_return` to `CommandStub#will_return`
+* add `CommandStub#will_cause(&blk)` for specifying desired side effects
+* add `CommandStub#will_stdout(str)` & `CommandStub#will_stderr(str)`. these will work differently for backtick than it will for system & exec.
 * maybe add `CommandStub#with_stdin(str)` for `spawn`?
 
+## RELEASE 0.5.0
+
+* FEATURE: `CommandStub#and_output` can be used on command stubs to set the output of a command without setting the exit status.
+* ENHANCEMENT: `Kernel#spawn`, `Kernel.spawn`, & `Process.spawn` are now implemented well enough that `Open3.capture3` behaves as though spawn is not being monkey-patched when ShellMock is enabled (and therefore, spawn most definitely is being monkey-patched). This should apply to all of `Open3`'s methods, since they all delegate to `Open3.popen_run` or `Open3.pipeline_run`, both of which internally use `Kernel#spawn`, **however I only have a spec for `Open3.capture3`**.
+
 ## RELEASE 0.4.0
 
-* FEATURE: `Kernel#spawn` and `Kernel.spawn` are now supported, which means all of Open3 is, as all of that library eventually results in a `spawn` call.
+* FEATURE: `Kernel#spawn` and `Kernel.spawn` are now supported
 
 ## RELEASE 0.3.3
 

data/README.md

@@ -1,50 +1,80 @@
 # ShellMock
+[![Gem Version](https://badge.fury.io/rb/shell_mock.png)](http://badge.fury.io/rb/shell_mock)
+[![Build Status](https://secure.travis-ci.org/yarmiganosca/shell_mock.png)](http://travis-ci.org/yarmiganosca/shell_mock)
 
 It's [webmock](http://github.com/bblimke/webmock) for shell commands. It's pretty simple. You can do things like this:
 
 ```ruby
 require 'shell_mock/rspec'
 
-describe 'something' do
-  stub = ShellMock.stub_command('ls')
+RSpec.describe "shelling out to run 'ls'" do
+  before { ShellMock.enable }
+  after  { ShellMock.disable }
 
-  expect(system('ls')).to eq true
+  let(:stub) { ShellMock.stub_command('ls') }
 
-  expect(stub).to have_been_called
+  it "works"
+    expect(system('ls')).to eq true
+
+    expect(stub).to have_been_called
+  end
 end
 ```
 
-Currently, `` ` ``, `exec`, and `system` are supported. Nothing in the `Open3` standard library module is currently supported.
+This:
+1. enables ShellMock's monkey patches during the test
+2. creates a command stub that will match the command `"ls"` (by default it will exit `0` and have no output)
+3. shells out to run `"ls"` (in this case using `Kernel#system`)
+4. correctly expects that our command stub for `"ls"` will have recorded an invocation
 
-### More complex expectations are also supported.
+### You can narrow what invocations are matched to your command stub:
 
-Called exactly once: `expect(stub).to have_been_called.once`
+**Match env vars as well as the command:** `ShellMock.stub_command('ls').with_env({'FOO' => 'bar'})`
 
-Not called: `expect(stub).to_not have_been_called` or `expect(stub).to have_been_called.never`
+**Provide a more complete invocation:** `ShellMock.stub_command('ls $HOME')`
 
-Called exactly `n` times: `expect(stub).to have_been_called.times(n)`
+Shelling out to run `"ls"` won't match this command stub, but shelling out to run `"ls $HOME"` will. ShellMock always matches as strictly as possible, so if you stubbed `"ls"` and `"ls $HOME"`, invocations of `"ls $HOME'` would only ever match against the latter.
 
-Called more than `n` times: `expect(stub).to have_been_called.more_than(n)`
+### Setting the behavior of the command invocation:
 
-Called fewer than `n` times: `expect(stub).to have_been_called.fewer_than(n)`
+**Have the mock command invocation write to stdout:** `ShellMock.stub_command('ls').and_output("\n")`
 
-`less_than` is also an alias for `fewer_than`.
+**Set the mock command invocation's exit status:** `ShellMock.stub_command('ls').and_exit(2)`
 
-Right now, only exact command string matches are supported.
+If you want to both write to stdout and set the exit code (a common pair), `ShellMock.stub_command('ls').and_return("\n")` will both have the command invocation write the passed string to stdout, and will set the mock command invocation's exit status to `0`.
 
-### You can also set the output of the command invocation:
+### Specifying the expected number of command invocations:
 
-```ruby
-require 'shell_mock/rspec'
+**Called exactly once:** `expect(stub).to have_been_called.once`
 
-describe 'something' do
-  stub = ShellMock.stub_commmand('ls').and_return("\n")
+**Not called:** `expect(stub).to have_been_called.never`
 
-  expect(`ls`).to eq "\n"
+**Not called (using RSpec expectation negation):** `expect(stub).to_not have_been_called`
 
-  expect(stub).to have_been_called.once
-end
-```
+**Called exactly `n` times:** `expect(stub).to have_been_called.times(n)`
+
+**Called more than `n` times:** `expect(stub).to have_been_called.more_than(n)`
+
+**Called fewer than `n` times:** `expect(stub).to have_been_called.fewer_than(n)`
+
+`less_than` can be used as an alias for `fewer_than`
+## Limitations
+
+Currently, only exact string matches of the stubbed command string are supported. Basic regex support or more complex matching for arguments and flags may be added later.
+
+ShellMock supports stubbing these ways of shelling out in Ruby:
+* [`` Kernel#` ``](https://ruby-doc.org/core/Kernel.html#method-i-60) (aka "backticks")
+* [`%x` command literal](https://ruby-doc.org/docs/ruby-doc-bundle/Manual/man-1.4/syntax.html#command) (which delegates to backticks)
+* [`Kernel#system`](https://ruby-doc.org/core/Kernel.html#method-i-system)
+* [`Kernel#exec`](https://ruby-doc.org/core/Kernel.html#method-i-exec)
+* [`Kernel#spawn`](https://ruby-doc.org/core/Kernel.html#method-i-spawn)
+* [`Process.spawn`](https://ruby-doc.org/core/Process.html#method-c-spawn)
+* [the `Open3` module](https://ruby-doc.org/stdlib/libdoc/open3/rdoc/Open3.html) (since all its methods use `spawn`)
+
+ShellMock currently DOES NOT support stubbing these ways of shelling out in Ruby (but will):
+* [`IO.popen`](https://ruby-doc.org/core/IO.html#method-c-popen)
+* [`PTY.spawn`](https://ruby-doc.org/stdlib/libdoc/pty/rdoc/PTY.html#method-c-spawn)
+* [passing a string that starts with `"|"`](https://devver.wordpress.com/2009/07/13/a-dozen-or-so-ways-to-start-sub-processes-in-ruby-part-2/) to [`Kernel#open`](https://ruby-doc.org/core/Kernel.html#method-i-open)
 
 ## Installation
 

data/lib/shell_mock.rb

@@ -24,32 +24,39 @@ module ShellMock
     @let_commands_run
   end
 
+  # smell; this is a mistake of a method that will only confuse people
   def self.dont_let_commands_run?
     !let_commands_run?
   end
 
   def self.enable
-    ShellMock.monkey_patches.each do |patch|
-      patch.enable_for(Kernel.eigenclass) unless Kernel.respond_to?(patch.alias_for_original, true)
-      patch.enable_for(Kernel)            unless Object.new.respond_to?(patch.alias_for_original, true)
-    end
+    ShellMock.monkey_patches.each(&:enable)
+
+    @enabled = true
+
+    true
   end
 
   def self.disable
-    ShellMock.monkey_patches.each do |patch|
-      patch.disable_for(Kernel.eigenclass) if Kernel.respond_to?(patch.alias_for_original, true)
-      patch.disable_for(Kernel)            if Object.new.respond_to?(patch.alias_for_original, true)
-    end
+    ShellMock.monkey_patches.each(&:disable)
 
     StubRegistry.clear
+
+    @enabled = false
+
+    true
+  end
+
+  def self.enabled?
+    @enabled
   end
 
   def self.monkey_patches
-    [
-      SpawnMonkeyPatch,
-      SystemMonkeyPatch,
-      ExecMonkeyPatch,
-      BacktickMonkeyPatch
+    @monkey_patches ||= [
+      SpawnMonkeyPatch.new,
+      SystemMonkeyPatch.new,
+      ExecMonkeyPatch.new,
+      BacktickMonkeyPatch.new,
     ]
   end
 end

data/lib/shell_mock/backtick_monkey_patch.rb

@@ -0,0 +1,33 @@
+require 'shell_mock/monkey_patch'
+require 'shell_mock/stub_registry'
+require 'shell_mock/no_stub_specified'
+
+module ShellMock
+  class BacktickMonkeyPatch < MonkeyPatch
+    def method_name
+      "`"
+    end
+
+    def interpolatable_name
+      :backtick
+    end
+
+    def override(command)
+      stub = StubRegistry.stub_matching({}, command, {})
+
+      if stub
+        stub.called_with({}, command, {})
+
+        stub.side_effect.call
+
+        __un_shell_mocked_backtick(stub.to_oneliner)
+      else
+        if ShellMock.let_commands_run?
+          __un_shell_mocked_backtick(command)
+        else
+          raise NoStubSpecified.new({}, command, {})
+        end
+      end
+    end
+  end
+end

data/lib/shell_mock/call_verifier.rb

@@ -1,21 +1,26 @@
 module ShellMock
   class CallVerifier
     def initialize
-      match_calls_when { |calls| calls.any? }
+      more_than(0)
     end
 
-    def matches?(actual)
-      @actual = actual
+    def times(n)
+      match_calls_when { |calls| calls == n }
 
-      condition.call(actual.calls)
+      self
     end
 
-    def failure_message
-      "#{actual.command} was expected."
+    def fewer_than(n)
+      match_calls_when { |calls| calls < n }
+
+      self
     end
+    alias less_than fewer_than
 
-    def failure_message_when_negated
-      "#{actual.command} was not expected."
+    def more_than(n)
+      match_calls_when { |calls| calls > n }
+
+      self
     end
 
     def once
@@ -26,28 +31,23 @@ module ShellMock
       times(0)
     end
 
-    def times(n)
-      match_calls_when { |calls| calls.size == n }
+    def matches?(command_stub)
+      @command_stub = command_stub
 
-      self
+      condition.call(command_stub.calls)
     end
 
-    def fewer_than(n)
-      match_calls_when { |calls| calls.size < n }
-
-      self
+    def failure_message
+      "#{command_stub.command} was expected."
     end
-    alias less_than fewer_than
-
-    def more_than(n)
-      match_calls_when { |calls| calls.size > n }
 
-      self
+    def failure_message_when_negated
+      "#{command_stub.command} was not expected."
     end
 
     private
 
-    attr_reader :actual, :condition
+    attr_reader :command_stub, :condition
 
     def match_calls_when(&blk)
       @condition = blk

data/lib/shell_mock/command_stub.rb

@@ -3,7 +3,7 @@ require 'shell_mock/stub_registry'
 
 module ShellMock
   class CommandStub
-    attr_reader :command, :expected_output, :exitstatus, :env, :options, :side_effect, :writer
+    attr_reader :command, :output, :exitstatus, :env, :options, :side_effect
 
     def initialize(command)
       @command     = command
@@ -21,19 +21,24 @@ module ShellMock
       self
     end
 
-    def with_option(option)
+    def with_options(options)
       @options = options
 
       self
     end
 
-    def and_return(expected_output)
-      @expected_output = expected_output
-      @exitstatus      = 0
+    def and_output(output)
+      @output = output
 
       self
     end
 
+    def and_return(output)
+      self.
+        and_output(output).
+        and_exit(0)
+    end
+
     def and_exit(exitstatus)
       @exitstatus = exitstatus
 
@@ -41,24 +46,26 @@ module ShellMock
     end
 
     def calls
-      @calls ||= []
+      @calls ||= 0
 
       marshaled_signatures.each do |marshaled_signature|
-        @calls << Marshal.load(marshaled_signature)
+        @calls += 1
       end
 
       @calls
     end
 
     def called_with(env, command, options)
-      signature = Marshal.dump([env, command, options])
+      writer.puts("called\n")
+    end
 
-      writer.puts(signature)
+    def to_oneliner
+      "echo '#{output}' && exit #{exitstatus}"
     end
 
     private
 
-    attr_reader :reader
+    attr_reader :reader, :writer
 
     def marshaled_signatures
       messages = ""

data/lib/shell_mock/exec_monkey_patch.rb

@@ -0,0 +1,33 @@
+require 'shell_mock/monkey_patch'
+require 'shell_mock/stub_registry'
+require 'shell_mock/no_stub_specified'
+
+module ShellMock
+  class ExecMonkeyPatch < MonkeyPatch
+    def method_name
+      :exec
+    end
+
+    def override(env, command = nil, **options)
+      env, command = {}, env if command.nil?
+
+      # other arg manipulation can go here if necessary
+
+      stub = StubRegistry.stub_matching(env, command, options)
+
+      if stub
+        stub.called_with(env, command, options)
+
+        stub.side_effect.call
+
+        __un_shell_mocked_exec(stub.to_oneliner)
+      else
+        if ShellMock.let_commands_run?
+          __un_shell_mocked_exec(env, command, **options)
+        else
+          raise NoStubSpecified.new(env, command, options)
+        end
+      end
+    end
+  end
+end

data/lib/shell_mock/monkey_patch.rb

@@ -2,42 +2,49 @@ require 'shell_mock/no_stub_specified'
 
 module ShellMock
   class MonkeyPatch
-    attr_reader :original, :alias_for_original
+    def enable
+      enable_for(Kernel.eigenclass) unless Kernel.respond_to?(method_alias, true)
+      enable_for(Kernel)            unless Object.new.respond_to?(method_alias, true)
+    end
+
+    def disable
+      disable_for(Kernel.eigenclass) if Kernel.respond_to?(method_alias, true)
+      disable_for(Kernel)            if Object.new.respond_to?(method_alias, true)
+    end
+
+    private
 
-    def initialize(original_name, interpolatable_name = original_name, &block)
-      @original           = original_name
-      @alias_for_original = "__un_shell_mocked_#{interpolatable_name}"
-      @replacement        = "__shell_mocked_#{interpolatable_name}"
-      @block              = block
+    def method_alias
+      "__un_shell_mocked_#{interpolatable_name}"
     end
 
-    def to_proc
-      @block.to_proc
+    def interpolatable_name
+      method_name
     end
 
     def enable_for(class_or_module)
-      class_or_module.send(:alias_method, alias_for_original, original)
+      class_or_module.send(:alias_method, method_alias, method_name)
 
       begin
         # so we don't have to see method redefinition warnings
-        class_or_module.send(:remove_method, original)
+        class_or_module.send(:remove_method, method_name)
       rescue NameError
       end
 
-      class_or_module.send(:define_method, original, &to_proc)
+      class_or_module.send(:define_method, method_name, &method(:override))
     end
 
     def disable_for(class_or_module)
       begin
         # so we don't have to see method redefinition warnings
-        class_or_module.send(:remove_method, original)
+        class_or_module.send(:remove_method, method_name)
       rescue NameError
       end
 
-      class_or_module.send(:alias_method, original, alias_for_original)
+      class_or_module.send(:alias_method, method_name, method_alias)
 
       begin
-        class_or_module.send(:remove_method, alias_for_original)
+        class_or_module.send(:remove_method, method_alias)
       rescue NameError
       end
     end

data/lib/shell_mock/monkey_patches.rb

@@ -1,91 +1,4 @@
-require 'shell_mock/monkey_patch'
-require 'shell_mock/stub_registry'
-require 'shell_mock/no_stub_specified'
-
-module ShellMock
-  SpawnMonkeyPatch = MonkeyPatch.new(:spawn) do |env, command = nil, **options|
-    env, command = {}, env if command.nil?
-
-    # other arg manipulation can go here if necessary
-
-    stub = StubRegistry.stub_matching(env, command, options)
-
-    if stub
-      stub.side_effect.call
-      stub.called_with(env, command, options)
-
-      __un_shell_mocked_spawn("exit #{stub.exitstatus}")
-    else
-      if ShellMock.let_commands_run?
-        __un_shell_mocked_spawn(env, command, **options)
-      else
-        raise NoStubSpecified.new(env, command, options)
-      end
-    end
-  end
-
-  SystemMonkeyPatch = MonkeyPatch.new(:system) do |env, command = nil, **options|
-    env, command = {}, env if command.nil?
-
-    # other arg manipulation can go here if necessary
-
-    stub = StubRegistry.stub_matching(env, command, options)
-
-    if stub
-      stub.side_effect.call
-      stub.called_with(env, command, options)
-      __un_shell_mocked_backtick("exit #{stub.exitstatus}")
-
-      return stub.exitstatus == 0
-    else
-      if ShellMock.let_commands_run?
-        __un_shell_mocked_system(env, command, **options)
-      else
-        raise NoStubSpecified.new(env, command, options)
-      end
-    end
-  end
-
-  # This feels very boilerplatey because Kernel::system and Kernel::exec
-  # have very similar if not identical method signatures. I'm not sure
-  # whether extracting the commonalities would be worth it or would just
-  # confuse.
-  ExecMonkeyPatch = MonkeyPatch.new(:exec) do |env, command = nil, **options|
-    env, command = {}, env if command.nil?
-
-    # other arg manipulation can go here if necessary
-
-    stub = StubRegistry.stub_matching(env, command, options)
-
-    if stub
-      stub.side_effect.call
-      stub.called_with(env, command, options)
-
-      exit stub.exitstatus
-    else
-      if ShellMock.let_commands_run?
-        __un_shell_mocked_exec(env, command, **options)
-      else
-        raise NoStubSpecified.new(env, command, options)
-      end
-    end
-  end
-
-  BacktickMonkeyPatch = MonkeyPatch.new('`', :backtick) do |command|
-    stub = StubRegistry.stub_matching({}, command, {})
-
-    if stub
-      stub.side_effect.call
-      stub.called_with({}, command, {})
-      __un_shell_mocked_backtick("exit #{stub.exitstatus}")
-
-      return stub.expected_output
-    else
-      if ShellMock.let_commands_run?
-        __un_shell_mocked_backtick(command)
-      else
-        raise NoStubSpecified.new({}, command, {})
-      end
-    end
-  end
-end
+require 'shell_mock/spawn_monkey_patch'
+require 'shell_mock/system_monkey_patch'
+require 'shell_mock/backtick_monkey_patch'
+require 'shell_mock/exec_monkey_patch'

data/lib/shell_mock/spawn_monkey_patch.rb

@@ -0,0 +1,45 @@
+require 'shell_mock/monkey_patch'
+require 'shell_mock/stub_registry'
+require 'shell_mock/no_stub_specified'
+
+module ShellMock
+  class SpawnMonkeyPatch < MonkeyPatch
+    def method_name
+      :spawn
+    end
+
+    def override(env, command = nil, **options)
+      env, command = {}, env if command.nil?
+
+      # other arg manipulation can go here if necessary
+
+      stub = StubRegistry.stub_matching(env, command, options)
+
+      if stub
+        stub.called_with(env, command, options)
+
+        stub.side_effect.call
+
+        __un_shell_mocked_spawn(stub.to_oneliner, **options)
+      else
+        if ShellMock.let_commands_run?
+          __un_shell_mocked_spawn(env, command, **options)
+        else
+          raise NoStubSpecified.new(env, command, options)
+        end
+      end
+    end
+
+    def enable
+      enable_for(Process.eigenclass) unless Process.respond_to?(method_alias, true)
+
+      super
+    end
+
+    def disable
+      super
+
+      disable_for(Process.eigenclass) if Process.respond_to?(method_alias, true)
+    end
+  end
+end

data/lib/shell_mock/stub_registry.rb

@@ -9,11 +9,14 @@ module ShellMock
 
     def stub_matching(env, command, options)
       matching_stubs = command_stubs.select do |command_stub|
-        command_stub.env <= env &&
-          command_stub.options <= options &&
-          command_stub.command == command
+        command_stub.command == command &&
+          command_stub.env <= env &&
+          command_stub.options <= options
       end
 
+      # question: Should we increment all the stubs that match?
+      #   What should users expect when they register a stub that
+      #   wholly "covers" another already-registered stub?
       matching_stubs.max_by do |command_stub|
         [env.size, options.size]
       end

data/lib/shell_mock/system_monkey_patch.rb

@@ -0,0 +1,33 @@
+require 'shell_mock/monkey_patch'
+require 'shell_mock/stub_registry'
+require 'shell_mock/no_stub_specified'
+
+module ShellMock
+  class SystemMonkeyPatch < MonkeyPatch
+    def method_name
+      :system
+    end
+
+    def override(env, command = nil, **options)
+      env, command = {}, env if command.nil?
+
+      # other arg manipulation can go here if necessary
+
+      stub = StubRegistry.stub_matching(env, command, options)
+
+      if stub
+        stub.called_with(env, command, options)
+
+        stub.side_effect.call
+
+        __un_shell_mocked_system(stub.to_oneliner)
+      else
+        if ShellMock.let_commands_run?
+          __un_shell_mocked_system(env, command, **options)
+        else
+          raise NoStubSpecified.new(env, command, options)
+        end
+      end
+    end
+  end
+end

data/lib/shell_mock/version.rb

@@ -1,3 +1,3 @@
 module ShellMock
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shell_mock
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Chris Hoffman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-09-18 00:00:00.000000000 Z
+date: 2018-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,15 +114,19 @@ files:
 - bin/console
 - bin/setup
 - lib/shell_mock.rb
+- lib/shell_mock/backtick_monkey_patch.rb
 - lib/shell_mock/call_verifier.rb
 - lib/shell_mock/command_stub.rb
 - lib/shell_mock/core_ext/module.rb
+- lib/shell_mock/exec_monkey_patch.rb
 - lib/shell_mock/monkey_patch.rb
 - lib/shell_mock/monkey_patches.rb
 - lib/shell_mock/no_stub_specified.rb
 - lib/shell_mock/rspec.rb
 - lib/shell_mock/rspec/matchers.rb
+- lib/shell_mock/spawn_monkey_patch.rb
 - lib/shell_mock/stub_registry.rb
+- lib/shell_mock/system_monkey_patch.rb
 - lib/shell_mock/version.rb
 - shell_mock.gemspec
 homepage: http://www.github.com/yarmiganosca/shell_mock