test-cmd.rb 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b091ee25f1e890969728e516747d3104c20076d2a71973e02ccc346a9eb1cc8e
-  data.tar.gz: 4dbb449b245f30e89285b7cae84de42564e352a4f0790fcc3a8a048e21b3ede2
+  metadata.gz: 8f3880288c628fc25dc0a16dcee05222dc776ffb8cab098d2fad3610534ebded
+  data.tar.gz: 39573f323c733d4fef70b3e784c3b6c4f956f7da60e0c1bbe7e454d51487f003
 SHA512:
-  metadata.gz: 43fb7bb3700e9f384c253c8ab36ec3a1ebb2ec5e807b3af1d57883a64bddb132838086fc15b242ce3a65b85092941d23a040b866b3e173bed4bf5254e2829690
-  data.tar.gz: c314163ab04470596296e8644414bec98414955b7423a1cc5affe202184befedffaff5f1f63427b18dd192b356fe491d3ec85e1b1c5140857c185b3a7ea37402
+  metadata.gz: 3b8e25c54804ac4cfa14f4356a2ea9f3e7b97f994792ae3f77b60e19151d3ee66d84959a40347b82adf1e0b5c277c3d28ef81b85992a5a496881db8e695ca867
+  data.tar.gz: face7b9c865c69666ff8eb29393af0ce856777bdf70d617889021f3a8496c0d331be88c527eec3f861b606773d93b1ca70e634c7e08e4a12f60320d57777e5bd

data/.github/workflows/specs.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: [3.1, 3.2, 3.3]
+        ruby: [3.1, 3.2, 3.3, 4.0]
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v2

data/README.md

@@ -34,7 +34,6 @@ test-cmd.rb can be installed via rubygems.org:
 
 ### Commands
 
-
 ```ruby
 require "test-cmd"
 
@@ -60,19 +59,50 @@ p Test::Command
   .new("tr", "a-z", "A-Z")
   .stdin("hello")
   .stdout  # => "HELLO"
+
+##
+# Limit how much data is read from stdout and
+# stderr. At most 20k bytes is read from both:
+p Test::Command
+  .new("git")
+  .limit(stdout: 20_000, stderr: 20_000)
+  .argv("diff", "--cached")
+  .stdout
 ```
 
 <details>
 <summary>Environment</summary>
 <br>
 
+A command that is not given an environment inherits the parent's
+environment. When `env` is called, only the variables that are
+given to `env` are set on the spawned process, alongside `$PATH`
+which is always inherited. `$PATH` is inherited so that the
+command can still be found via path lookup.
+
 ```ruby
-require "test-cmd"
+##
+# Inherit the parent's environment. All variables
+# from the parent process are available.
+p Test::Command
+  .new("env")
+  .stdout
+
+##
+# Only $FOO and $BAR are set, plus the inherited
+# $PATH. Everything else is left behind.
+p Test::Command
+  .new("env")
+  .env("FOO" => "42", "BAR" => "7")
+  .stdout
 
+##
+# An empty hash yields only $PATH and the rest of
+# environment is left empty.
 p Test::Command
-  .new("ruby", "-e", "puts ENV['FOO']")
-  .env("FOO" => "42")
-  .stdout  # => "42\n"
+    .new("env")
+    .env({})
+    .stdout
 ```
 </details>
 

data/lib/test/command/version.rb

@@ -4,5 +4,5 @@ end unless defined?(Test)
 class Test::Command
   ##
   # @string [String]
-  VERSION = "2.4.0"
+  VERSION = "2.6.0"
 end

data/lib/test/command.rb

@@ -28,12 +28,13 @@ class Test::Command
   def initialize(cmd, *argv)
     @cmd = cmd
     @argv = argv.dup
-    @env = {}
+    @env = nil
     @status = nil
     @spawned = false
     @stdout = ""
     @stderr = ""
     @enoent = false
+    @limit = {stdout: nil, stderr: nil}
   end
 
   ##
@@ -49,7 +50,7 @@ class Test::Command
   #  Environment variables to set for the spawned command
   # @return [Test::Command]
   def env(env)
-    tap { @env.merge!(env) }
+    tap { (@env ||= {}).merge!(env) }
   end
 
   ##
@@ -67,6 +68,19 @@ class Test::Command
     tap { @stdin = data }
   end
 
+  ##
+  # Limits how many bytes of each stream are captured.
+  # A stream output beyond the limit is discarded, keeping
+  # memory bounded even for a command that streams a lot.
+  # @param [Integer, nil] stdout
+  #  Max bytes of stdout to read, or nil for unlimited
+  # @param [Integer, nil] stderr
+  #  Max bytes of stderr to read, or nil for unlimited
+  # @return [Test::Command]
+  def limit(stdout: nil, stderr: nil)
+    tap { @limit = {stdout:, stderr:} }
+  end
+
   ##
   # Spawns a command
   # @return [Test::Command]
@@ -77,7 +91,7 @@ class Test::Command
       @spawned = true
       @out, @err = Pipe.pair, Pipe.pair
       @pid = Process.spawn(
-        @env,
+        envp,
         @cmd, *@argv.map(&:to_s),
         {in: @in_r, out: @out.w, err: @err.w}
       )
@@ -85,8 +99,8 @@ class Test::Command
       @out.w.close
       @err.w.close
       @producer = Thread.new do
-        @stdout = @out.r.read
-        @stderr = @err.r.read
+        @stdout = read_limited(@out.r, @limit[:stdout])
+        @stderr = read_limited(@err.r, @limit[:stderr])
         Process.wait
         @status = $?
       ensure
@@ -232,6 +246,54 @@ class Test::Command
 
   private
 
+  ##
+  # Builds the environment passed to Process.spawn.
+  # The spawned process receives only the variables
+  # set with #env: every inherited variable is
+  # cleared, so an empty @env spawns with an empty
+  # environment.
+  # @return [Hash{String => String}]
+  def envp
+    if @env.nil?
+      ##
+      # Inherit the parent's environment
+      ENV.to_h
+    else
+      ##
+      # Clear all environment variables except those
+      # that are set by `@env`. Always inherit ${PATH}.
+      envp = ENV.except("PATH")
+                .each_key
+                .to_h { |key| [key, nil] }
+      envp.merge!(@env)
+    end
+  end
+
+  ##
+  # Reads up to +max+ bytes from a stream, then drains
+  # the remainder so a child writing more than the limit
+  # does not block on a full pipe. When +max+ is nil the
+  # entire stream is read.
+  # @param [IO] io
+  # @param [Integer, nil] max
+  # @return [String]
+  def read_limited(io, max)
+    return io.read if max.nil?
+    buf = +""
+    remaining = max
+    while remaining > 0 && (chunk = io.read(remaining))
+      buf << chunk
+      remaining -= chunk.bytesize
+    end
+    ##
+    # Drain whatever is left so the child can exit:
+    # the drained bytes are discarded, keeping memory
+    # bounded.
+    while (chunk = io.read(16_384))
+    end
+    buf
+  end
+
   ##
   # Returns a pipe pair used for the command's
   # standard input. When no input is set, the child

data/test/cmd_test.rb

@@ -38,6 +38,41 @@ class Test::Command
                      .env("FOO" => "42")
                      .stdout
     end
+
+    def test_ruby_env_only_given_keys
+      assert_equal "BAR\nFOO\nPATH\n",
+                  ::Test::Command.new("ruby", "-e", "puts ENV.keys.sort")
+                  .env("FOO" => "42", "BAR" => "7")
+                  .stdout
+    end
+
+    def test_ruby_env_empty_is_empty_env
+      assert_equal "PATH",
+                  ::Test::Command.new("ruby", "-e", "print ENV.keys.sort.join(\",\")")
+                  .env({})
+                  .stdout
+    end
+
+    def test_ruby_env_does_not_leak_inherited
+      assert_equal "true",
+                    ::Test::Command.new("ruby", "-e", "print ENV.key?('PATH')")
+                    .stdout
+    end
+
+    def test_ruby_env_path_carries_over_inherited
+      parent_path = ENV["PATH"]
+      assert_equal parent_path,
+                   ::Test::Command.new("ruby", "-e", "print ENV['PATH']")
+                     .stdout
+    end
+
+    def test_ruby_env_path_carries_over_empty
+      parent_path = ENV["PATH"]
+      assert_equal parent_path,
+                   ::Test::Command.new("ruby", "-e", "print ENV['PATH']")
+                     .env({})
+                     .stdout
+    end
   end
 
   ##
@@ -58,6 +93,43 @@ class Test::Command
     end
   end
 
+  ##
+  # Test::Command#limit
+  class LimitTest < Test
+    def test_ruby_limit_stdout
+      assert_equal "happy",
+                   ::Test::Command.new("printf", "%s", "happy days")
+                     .limit(stdout: 5)
+                     .stdout
+    end
+
+    def test_ruby_limit_stderr
+      assert_equal "smile",
+                   ::Test::Command.new("sh", "-c", "echo smile >&2")
+                     .limit(stderr: 5)
+                     .stderr
+    end
+
+    def test_ruby_limit_nil_is_unlimited
+      expect = "a" * 20_000
+      assert_equal expect,
+                   ::Test::Command.new("ruby", "-e", "print 'a' * 20_000")
+                     .stdout
+    end
+
+    def test_ruby_limit_drains_remaining_output
+      cmd = ::Test::Command.new("sh", "-c", "printf 'happy days'")
+        .limit(stdout: 5)
+        .spawn
+      assert_equal true, cmd.spawned?
+      ##
+      # A full pipe would block forever: the
+      # drain lets the child finish and capture
+      # its status
+      assert_equal 0, cmd.exit_status
+    end
+  end
+
   ##
   # Test::Command#{exit_status, status, success?}
   class ExitStatusTest < Test

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: test-cmd.rb
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Robert Gleeson