test-cmd.rb 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37a0fdfc106f74072dd6368cad33bdce7bd610a142a52b3996cf73e8a058e28e
+  data.tar.gz: f2eaa7173ee120d6bcf067554b3cabb8845b49efc555a8fc87083f30066992af
+SHA512:
+  metadata.gz: ad30fbeb8c4800d9f111ab23540878dd7b5d8cffc2229f41a8e4991fee00ebae1f47f6113f1bd2b8be70ac1fcf0af98424f86c3bd14de31aacbed5109d9fa5ce
+  data.tar.gz: 178e1d4842f6855d05ad9e9630c98a63338eebab148bafe2b75f85d3fac0a13a1eac7d1f819552adebcc85d2e6033ef8f52f612ea1f518476addf58c146dfa69

data/.github/workflows/specs.yml

@@ -0,0 +1,23 @@
+name: test-cmd.rb
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  specs:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby: [3.1, 3.2]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - run: bundle install
+    - run: bundle exec ruby test/*_test.rb

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.gems
+.bundle
+Gemfile.lock
+.yardoc/
+doc/
+pkg/

data/.gitlab-ci.yml

@@ -0,0 +1,16 @@
+stages:
+  - test
+
+test-ruby31:
+  stage: test
+  image: ruby:3.1.2
+  script:
+    - bundle install
+    - bundle exec ruby test/*_test.rb
+
+test-ruby32:
+  stage: test
+  image: ruby:3.2.0
+  script:
+    - bundle install
+    - bundle exec ruby test/*_test.rb

data/.projectile

@@ -0,0 +1 @@
+-.gems/

data/.rubocop.yml

@@ -0,0 +1,19 @@
+##
+# Plugins
+require:
+  - standard
+
+##
+# Defaults: standard-rb
+inherit_gem:
+  standard: config/base.yml
+
+AllCops:
+  TargetRubyVersion: 3.1
+  Include:
+    - 'lib/**/*.rb'
+    - 'test/**/*.rb'
+
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/test-cmd.rb'

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE

@@ -0,0 +1,15 @@
+Copyright (C) 2023 by 0x1eef <0x1eef@protonmail.com>
+
+Permission to use, copy, modify, and/or distribute this
+software for any purpose with or without fee is hereby
+granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
+ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,118 @@
+## About
+
+test-cmd.rb is a library for accessing the output streams
+(both stdout and stderr) of a spawned process. The library was
+first realized in a test environment, where it provided a path
+for verifying that when code examples are run they produce the
+expected output. The library can be generally useful outside a
+test environment, too.
+
+## Examples
+
+### Test::Unit
+
+The following example demonstrates how tests might be written with
+test-unit from the standard library. The
+[`Test::Cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html)
+module implements a
+[`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html#cmd-class_method)
+method that can be included into a
+testcase. The
+[`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html#cmd-class_method)
+method takes the command to run as its first and only argument:
+
+```ruby
+require "test/unit"
+require "test/cmd"
+
+class CmdTest < Test::Unit::TestCase
+  include Test::Cmd
+
+  def test_ruby_stdout
+    assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
+  end
+
+  def test_ruby_stderr
+    assert_equal "bar\n", cmd(%q(ruby -e '$stderr.puts "bar"')).stderr
+  end
+
+  def test_ruby_success_exit_status
+    assert_equal 0, cmd(%q(ruby -e 'exit 0')).exit_status
+  end
+
+  def test_ruby_failure_exit_status
+    assert_equal 1, cmd(%q(ruby -e 'exit 1')).exit_status
+  end
+end
+```
+
+### IO#sync
+
+Sometimes it can be neccessary to bypass Ruby's internal buffer and flush
+output to the operating system immediately, otherwise there can be unexpected
+results. Consider the following example, where the output will be
+`bar\nfoo\n` rather than `foo\nbar\n`:
+
+``` ruby
+##
+# test.rb
+pid = fork do
+  sleep(1)
+  puts "bar"
+end
+puts "foo"
+Process.wait(pid)
+
+##
+# cmd.rb
+p cmd("ruby test.rb").stdout # => "bar\nfoo\n"
+```
+
+And with output flushed to the operating system immediately:
+
+``` ruby
+##
+# test.rb
+$stdout.sync = true
+pid = fork do
+  sleep(1)
+  puts "bar"
+end
+puts "foo"
+Process.wait(pid)
+
+##
+# cmd.rb
+p cmd("ruby test.rb").stdout # => "foo\nbar\n"
+```
+
+## Sources
+
+* [Source code (GitHub)](https://github.com/0x1eef/test-cmd.rb#readme)
+* [Source code (GitLab)](https://gitlab.com/0x1eef/test-cmd.rb#about)
+
+## Install
+
+test-cmd.rb is distributed as a RubyGem through its git repositories. <br>
+[GitHub](https://github.com/0x1eef/test-cmd.rb),
+and
+[GitLab](https://gitlab.com/0x1eef/test-cmd.rb)
+are available as sources.
+
+``` ruby
+# Gemfile
+gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.4.1"
+```
+
+**Rubygems.org**
+
+test-cmd.rb can also be installed via rubygems.org.
+
+    gem install test-cmd.rb
+
+## License
+
+[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/).
+<br>
+See [LICENSE](./LICENSE).
+

data/lib/test/cmd.rb

@@ -0,0 +1 @@
+require_relative "../test-cmd"

data/lib/test-cmd.rb

@@ -0,0 +1,76 @@
+module Test
+end unless defined?(Test)
+
+##
+# test-cmd.rb is a library for accessing the output streams
+# (both stdout and stderr) of a spawned process. The library was
+# first realized in a test environment, where it provided a path
+# for verifying that when code examples are run they produce the
+# expected output. The library can be generally useful outside a
+# test environment, too.
+module Test::Cmd
+  class Result
+    require "tempfile"
+    ##
+    # @return [String]
+    #  Returns the contents of stdout
+    attr_reader :stdout
+
+    ##
+    # @return [String]
+    #  Returns the contents of stderr
+    attr_reader :stderr
+
+    ## @return [Process::Status]
+    #  Returns the status of a process
+    attr_reader :status
+
+    ##
+    # @param [Tempfile] stdout
+    # @param [Tempfile] stderr
+    # @param [Process::Status] pstatus
+    # @return [Test::Cmd::Result]
+    def initialize(stdout, stderr, pstatus)
+      @stdout = stdout.tap(&:rewind).read
+      @stderr = stderr.tap(&:rewind).read
+      @status = pstatus
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the exit status of a process
+    def exit_status
+      @status.exitstatus
+    end
+
+    ##
+    # Yields each line of stdout when the command
+    # was successful, or each line of stderr when
+    # the command was not successful.
+    #
+    # @return [Enumerator]
+    #  Returns an Enumerator when a block is not given.
+    def each_line
+      return enum_for(:each_line) unless block_given?
+      io = @status.success? ? @stdout : @stderr
+      io.each_line.each { yield(_1.chomp) }
+    end
+  end
+
+  ##
+  # @param [String] cmd
+  #  A command to execute
+  #
+  # @return [Test::Cmd::Result]
+  #  Returns an instance of {Test::Cmd::Result Test::Cmd::Result}
+  def cmd(cmd)
+    out = Tempfile.new("cmd-stdout").tap(&:unlink)
+    err = Tempfile.new("cmd-stderr").tap(&:unlink)
+    Process.wait spawn(cmd, {err:, out:})
+    Result.new(out, err, $?)
+  ensure
+    out.close
+    err.close
+  end
+  module_function :cmd
+end

data/test/setup.rb

@@ -0,0 +1,3 @@
+require "bundler/setup"
+require "test/unit"
+require "test/cmd"

data/test/test_cmd_test.rb

@@ -0,0 +1,49 @@
+require_relative "setup"
+
+class CmdTest < Test::Unit::TestCase
+  include Test::Cmd
+
+  def test_ruby_stdout
+    assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
+  end
+
+  def test_ruby_stderr
+    assert_equal "bar\n", cmd(%q(ruby -e '$stderr.puts "bar"')).stderr
+  end
+
+  def test_ruby_success_exit_status
+    assert_equal 0, cmd(%q(ruby -e 'exit 0')).exit_status
+  end
+
+  def test_ruby_failure_exit_status
+    assert_equal 1, cmd(%q(ruby -e 'exit 1')).exit_status
+  end
+
+  def test_stdout_with_fork
+    code = <<-CODE.each_line.map { _1.chomp.strip }.join(";")
+      $stdout.sync = true
+      pid = fork do
+        sleep(1)
+        puts "bar"
+      end
+      puts "foo"
+      Process.wait(pid)
+    CODE
+    assert_equal "foo\nbar\n", cmd(%Q(ruby -e '#{code}')).stdout
+  end
+
+  def test_each_line_stdout
+    run = false
+    cmd(%q(ruby -e '$stdout.puts "FooBar"'))
+    .each_line do
+      run = true
+      assert_equal _1, "FooBar"
+    end
+    assert_equal true, run
+  end
+
+  def test_each_line_returns_enum
+    assert_instance_of Enumerator,
+                       cmd(%q(ruby -e '$stdout.puts "FooBar"')).each_line
+  end
+end

data/test-cmd.rb.gemspec

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |gem|
+  gem.name = "test-cmd.rb"
+  gem.authors = ["0x1eef"]
+  gem.email = ["0x1eef@protonmail.com"]
+  gem.homepage = "https://github.com/0x1eef/test-cmd.rb#readme"
+  gem.version = "0.4.1"
+  gem.required_ruby_version = ">= 3.0"
+  gem.licenses = ["0BSD"]
+  gem.files = `git ls-files`.split($/)
+  gem.require_paths = ["lib"]
+  gem.summary = "test-cmd.rb provides access to the output streams " \
+                "(both stdout and stderr) of a spawned process."
+  gem.description = gem.summary
+  gem.add_development_dependency "test-unit", "~> 3.5.7"
+  gem.add_development_dependency "yard", "~> 0.9"
+  gem.add_development_dependency "redcarpet", "~> 3.5"
+  gem.add_development_dependency "standard", "~> 1.24"
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: test-cmd.rb
+version: !ruby/object:Gem::Version
+  version: 0.4.1
+platform: ruby
+authors:
+- '0x1eef'
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.7
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+description: test-cmd.rb provides access to the output streams (both stdout and stderr)
+  of a spawned process.
+email:
+- 0x1eef@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/specs.yml"
+- ".gitignore"
+- ".gitlab-ci.yml"
+- ".projectile"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE
+- README.md
+- lib/test-cmd.rb
+- lib/test/cmd.rb
+- test-cmd.rb.gemspec
+- test/setup.rb
+- test/test_cmd_test.rb
+homepage: https://github.com/0x1eef/test-cmd.rb#readme
+licenses:
+- 0BSD
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: test-cmd.rb provides access to the output streams (both stdout and stderr)
+  of a spawned process.
+test_files: []