test-cmd.rb 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 37a0fdfc106f74072dd6368cad33bdce7bd610a142a52b3996cf73e8a058e28e
4
- data.tar.gz: f2eaa7173ee120d6bcf067554b3cabb8845b49efc555a8fc87083f30066992af
3
+ metadata.gz: d9c8ce3140a3961899e285245cbd7d6ceee4caf38508b268ba5500388bfa1aa8
4
+ data.tar.gz: 907ef5b303a8edfbdcb79930a40274c6976c79a9f78f5754c456adcff745f1e8
5
5
  SHA512:
6
- metadata.gz: ad30fbeb8c4800d9f111ab23540878dd7b5d8cffc2229f41a8e4991fee00ebae1f47f6113f1bd2b8be70ac1fcf0af98424f86c3bd14de31aacbed5109d9fa5ce
7
- data.tar.gz: 178e1d4842f6855d05ad9e9630c98a63338eebab148bafe2b75f85d3fac0a13a1eac7d1f819552adebcc85d2e6033ef8f52f612ea1f518476addf58c146dfa69
6
+ metadata.gz: 03ab91c5888319ad5d6beb8ab45eac1d4749ba39607e09e5d7866af08027dced706b428c6dd80d077ac53ed4536c594068d87394ffdaaf3c0528d11c5fc690fb
7
+ data.tar.gz: eba0d96c1277ab435d51a2a8ce21c6269d98527224d15982a9ed3c967df56e820285b964fe8a984b9ceb6ec1cb468098777c733a220564be0c25399e6e190211
data/README.md CHANGED
@@ -13,21 +13,14 @@ test environment, too.
13
13
 
14
14
  The following example demonstrates how tests might be written with
15
15
  test-unit from the standard library. The
16
- [`Test::Cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html)
17
- module implements a
18
- [`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html#cmd-class_method)
19
- method that can be included into a
20
- testcase. The
21
- [`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html#cmd-class_method)
22
- method takes the command to run as its first and only argument:
16
+ [`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/CmdMixin.html#cmd-instance_method)
17
+ method is given the name of a command, along with any arguments:
23
18
 
24
19
  ```ruby
25
20
  require "test/unit"
26
21
  require "test/cmd"
27
22
 
28
23
  class CmdTest < Test::Unit::TestCase
29
- include Test::Cmd
30
-
31
24
  def test_ruby_stdout
32
25
  assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
33
26
  end
@@ -46,6 +39,23 @@ class CmdTest < Test::Unit::TestCase
46
39
  end
47
40
  ```
48
41
 
42
+ ### Builder
43
+
44
+ test-cmd.rb provides an API that is similar to Rust's
45
+ [Command API](https://doc.rust-lang.org/std/process/struct.Command.html).
46
+ <br>
47
+ The
48
+ [API reference](https://0x1eef.github.io/x/test-cmd.rb)
49
+ covers it in more-depth:
50
+
51
+ ``` ruby
52
+ require "test/cmd"
53
+ str = cmd("du")
54
+ .arg("-s").arg("-h")
55
+ .spawn.stdout
56
+ puts str
57
+ ```
58
+
49
59
  ### IO#sync
50
60
 
51
61
  Sometimes it can be neccessary to bypass Ruby's internal buffer and flush
@@ -101,7 +111,7 @@ are available as sources.
101
111
 
102
112
  ``` ruby
103
113
  # Gemfile
104
- gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.4.1"
114
+ gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.5.0"
105
115
  ```
106
116
 
107
117
  **Rubygems.org**
data/lib/test-cmd.rb CHANGED
@@ -1,76 +1,124 @@
1
1
  module Test
2
- end unless defined?(Test)
3
-
4
- ##
5
- # test-cmd.rb is a library for accessing the output streams
6
- # (both stdout and stderr) of a spawned process. The library was
7
- # first realized in a test environment, where it provided a path
8
- # for verifying that when code examples are run they produce the
9
- # expected output. The library can be generally useful outside a
10
- # test environment, too.
11
- module Test::Cmd
12
- class Result
2
+ ##
3
+ # test-cmd.rb is a library for accessing the output streams
4
+ # (both stdout and stderr) of a spawned process. The library was
5
+ # first realized in a test environment, where it provided a path
6
+ # for verifying that when code examples are run they produce the
7
+ # expected output. The library can be generally useful outside a
8
+ # test environment, too.
9
+ class Test::Cmd
13
10
  require "tempfile"
11
+
12
+ ##
13
+ # @param [String] cmd
14
+ # A command to spawn.
15
+ # @param [Array<String>] args
16
+ # An array of command-line arguments.
17
+ # @return [Test::Cmd]
18
+ def initialize(cmd, args = [])
19
+ @cmd = cmd
20
+ @args = args.dup
21
+ @out = Tempfile.new("cmd-stdout").tap(&:unlink)
22
+ @err = Tempfile.new("cmd-stderr").tap(&:unlink)
23
+ @status = nil
24
+ @spawned = false
25
+ end
26
+
27
+ ##
28
+ # @param [String, #to_s] arg
29
+ # A command-line argument.
30
+ # @return [Test::Cmd]
31
+ def arg(arg)
32
+ tap do
33
+ @args.push(arg)
34
+ end
35
+ end
36
+
37
+ ##
38
+ # @param [Array<String, #to_s>] args
39
+ # One or more command-line arguments.
40
+ # @return [Test::Cmd]
41
+ def args(*args)
42
+ tap do
43
+ @args.concat(args)
44
+ end
45
+ end
46
+
47
+ ##
48
+ # Spawns a command.
49
+ # @return [Test::Cmd]
50
+ def spawn
51
+ tap do
52
+ @spawned = true
53
+ Process.wait Process.spawn(@cmd, *@args, {out: @out, err: @err})
54
+ @status = $?
55
+ end
56
+ ensure
57
+ [stdout,stderr]
58
+ end
59
+
14
60
  ##
15
61
  # @return [String]
16
- # Returns the contents of stdout
17
- attr_reader :stdout
62
+ # Returns the contents of stdout.
63
+ def stdout
64
+ spawn unless @spawned
65
+ @stdout ||= @out.tap(&:rewind).read
66
+ ensure
67
+ @out.close unless @out.closed?
68
+ end
18
69
 
19
70
  ##
20
71
  # @return [String]
21
- # Returns the contents of stderr
22
- attr_reader :stderr
72
+ # Returns the contents of stderr.
73
+ def stderr
74
+ spawn unless @spawned
75
+ @stderr ||= @err.tap(&:rewind).read
76
+ ensure
77
+ @err.close unless @err.closed?
78
+ end
23
79
 
24
80
  ## @return [Process::Status]
25
81
  # Returns the status of a process
26
- attr_reader :status
27
-
28
- ##
29
- # @param [Tempfile] stdout
30
- # @param [Tempfile] stderr
31
- # @param [Process::Status] pstatus
32
- # @return [Test::Cmd::Result]
33
- def initialize(stdout, stderr, pstatus)
34
- @stdout = stdout.tap(&:rewind).read
35
- @stderr = stderr.tap(&:rewind).read
36
- @status = pstatus
82
+ def status
83
+ spawn unless @spawned
84
+ @status
37
85
  end
38
86
 
39
87
  ##
40
88
  # @return [Integer]
41
89
  # Returns the exit status of a process
42
90
  def exit_status
43
- @status.exitstatus
91
+ status.exitstatus
44
92
  end
45
93
 
46
94
  ##
47
95
  # Yields each line of stdout when the command
48
96
  # was successful, or each line of stderr when
49
97
  # the command was not successful.
50
- #
51
98
  # @return [Enumerator]
52
99
  # Returns an Enumerator when a block is not given.
53
100
  def each_line
54
101
  return enum_for(:each_line) unless block_given?
102
+ spawn unless @spawned
55
103
  io = @status.success? ? @stdout : @stderr
56
104
  io.each_line.each { yield(_1.chomp) }
57
105
  end
58
106
  end
59
107
 
60
- ##
61
- # @param [String] cmd
62
- # A command to execute
63
- #
64
- # @return [Test::Cmd::Result]
65
- # Returns an instance of {Test::Cmd::Result Test::Cmd::Result}
66
- def cmd(cmd)
67
- out = Tempfile.new("cmd-stdout").tap(&:unlink)
68
- err = Tempfile.new("cmd-stderr").tap(&:unlink)
69
- Process.wait spawn(cmd, {err:, out:})
70
- Result.new(out, err, $?)
71
- ensure
72
- out.close
73
- err.close
108
+ module CmdMixin
109
+ ##
110
+ # @param [String] cmd
111
+ # A command to execute
112
+ # @param [Array<String>] args
113
+ # An array of command-line arguments.
114
+ # @return [Test::Cmd]
115
+ # Returns an instance of {Test::Cmd Test::Cmd}
116
+ def cmd(cmd, args = [])
117
+ Test::Cmd.new(cmd, args)
118
+ end
74
119
  end
75
- module_function :cmd
120
+ end
121
+
122
+ module Kernel
123
+ include Test::CmdMixin
76
124
  end
@@ -1,8 +1,6 @@
1
1
  require_relative "setup"
2
2
 
3
3
  class CmdTest < Test::Unit::TestCase
4
- include Test::Cmd
5
-
6
4
  def test_ruby_stdout
7
5
  assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
8
6
  end
data/test-cmd.rb.gemspec CHANGED
@@ -5,13 +5,14 @@ Gem::Specification.new do |gem|
5
5
  gem.authors = ["0x1eef"]
6
6
  gem.email = ["0x1eef@protonmail.com"]
7
7
  gem.homepage = "https://github.com/0x1eef/test-cmd.rb#readme"
8
- gem.version = "0.4.1"
8
+ gem.version = "0.5.0"
9
9
  gem.required_ruby_version = ">= 3.0"
10
10
  gem.licenses = ["0BSD"]
11
11
  gem.files = `git ls-files`.split($/)
12
12
  gem.require_paths = ["lib"]
13
13
  gem.summary = "test-cmd.rb provides access to the output streams " \
14
14
  "(both stdout and stderr) of a spawned process."
15
+ gem.metadata = { "documentation_uri" => "https://0x1eef.github.io/x/test-cmd.rb/" }
15
16
  gem.description = gem.summary
16
17
  gem.add_development_dependency "test-unit", "~> 3.5.7"
17
18
  gem.add_development_dependency "yard", "~> 0.9"
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: test-cmd.rb
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.1
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - '0x1eef'
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2024-01-07 00:00:00.000000000 Z
11
+ date: 2024-01-30 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: test-unit
@@ -90,7 +90,8 @@ files:
90
90
  homepage: https://github.com/0x1eef/test-cmd.rb#readme
91
91
  licenses:
92
92
  - 0BSD
93
- metadata: {}
93
+ metadata:
94
+ documentation_uri: https://0x1eef.github.io/x/test-cmd.rb/
94
95
  post_install_message:
95
96
  rdoc_options: []
96
97
  require_paths: