Module: Toys::Testing

Defined in:
lib/toys/testing.rb

Overview

Helpers for writing tool tests.

EXPERIMENTAL: Interfaces are subject to change.

Instance Method Summary collapse

Instance Method Details

#capture_separate_tool(cmd, **opts) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result

Runs the tool corresponding to the given command line, and returns the data written to STDOUT. This is equivalent to calling #exec_separate_tool with the keyword arguments out: :capture, background: false, and calling #captured_out on the result.

Unlike #capture_tool, this method does not use "fork", and thus can be called in an environment such as JRuby or Ruby on Windows.

Parameters:

  • cmd (String, Array<String>) —

    The command to execute.

  • opts (keywords) —

    The command options.

Yield Parameters:

Returns:



132
133
134
135
 
# File 'lib/toys/testing.rb', line 132

def capture_separate_tool(cmd, **opts, &block)
  opts = opts.merge(out: :capture, background: false)
  exec_separate_tool(cmd, **opts, &block).captured_out
end

#capture_tool(cmd, **opts) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result

Runs the tool corresponding to the given command line, and returns the data written to STDOUT. This is equivalent to calling #exec_tool with the keyword arguments out: :capture, background: false, and calling #captured_out on the result.

Note: this method uses "fork" to execute the tool. If you are using an environment without "fork" support, such as JRuby oor Ruby on Windows, consider #capture_separate_tool.

Parameters:

  • cmd (String, Array<String>) —

    The command to execute.

  • opts (keywords) —

    The command options.

Yield Parameters:

Returns:



107
108
109
110
 
# File 'lib/toys/testing.rb', line 107

def capture_tool(cmd, **opts, &block)
  opts = opts.merge(out: :capture, background: false)
  exec_tool(cmd, **opts, &block).captured_out
end

#control_tool(cmd, **opts) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result

Runs the tool corresponding to the given command line, managing streams using a controller. This is equivalent to calling #exec_tool with the keyword arguments:

out: :controller,
err: :controller,
in: :controller,
background: block.nil?

If a block is given, the command is run in the foreground, the controller is passed to the block during the run, and a result object is returned. If no block is given, the command is run in the background, and the controller object is returned.

Parameters:

  • cmd (String, Array<String>) —

    The command to execute.

  • opts (keywords) —

    The command options.

Yield Parameters:

Returns:



162
163
164
165
 
# File 'lib/toys/testing.rb', line 162

def control_tool(cmd, **opts, &block)
  opts = opts.merge(out: :controller, err: :controller, in: :controller, background: block.nil?)
  exec_tool(cmd, **opts, &block)
end

#exec_separate_tool(cmd, **opts) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result

Runs the tool corresponding to the given command line, provided as an array of arguments, in a separately spawned process, and returns a Exec::Result.

Unlike #exec_tool, this method does not use the shared CLI, but instead spawns a completely new Toys process for each run. It is thus slower than #exec_tool, but compatible with environments without "fork" support, such as JRuby or Ruby on Windows.

Supported keyword arguments are the same as those defined by the Toys::Utils::Exec class. If a block is given, a Toys::Utils::Exec::Controller is yielded to it. For more info, see the documentation for Toys::Utils::Exec#exec.

Parameters:

  • cmd (String, Array<String>) —

    The command to execute.

  • opts (keywords) —

    The command options.

Yield Parameters:

Returns:



81
82
83
84
85
 
# File 'lib/toys/testing.rb', line 81

def exec_separate_tool(cmd, **opts, &block)
  cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
  cmd = [::RbConfig.ruby, "--disable=gems", ::Toys.executable_path] + cmd
  self.class.toys_exec.exec(cmd, **opts, &block)
end

#exec_tool(cmd, **opts) {|controller| ... } ⇒ Toys::Utils::Exec::Controller, Toys::Utils::Exec::Result

Runs the tool corresponding to the given command line, provided as an array of arguments, and returns a Exec::Result.

By default, a single CLI is shared among the tests in each test class or describe block. Thus, tools are loaded only once, and the loader is shared across the tests. If you need to isolate loading for a test, create a separate CLI and pass it in using the :cli keyword argument.

All other keyword arguments are the same as those defined by the Toys::Utils::Exec class. If a block is given, a Toys::Utils::Exec::Controller is yielded to it. For more info, see the documentation for Toys::Utils::Exec#exec.

This method uses "fork" to isolate the run of the tool. On an environment without "fork" support, such as JRuby or Ruby on Windows, consider #exec_separate_tool.

Parameters:

  • cmd (String, Array<String>) —

    The command to execute.

  • opts (keywords) —

    The command options.

Yield Parameters:

Returns:



48
49
50
51
52
53
54
 
# File 'lib/toys/testing.rb', line 48

def exec_tool(cmd, **opts, &block)
  cli = opts.delete(:cli) || toys_cli
  cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
  cli.loader.lookup(cmd)
  tool_caller = proc { ::Kernel.exit(cli.run(*cmd)) }
  self.class.toys_exec.exec_proc(tool_caller, **opts, &block)
end

#toys_cli ⇒ Toys::CLI

Returns the Toys CLI for this test class. By default, a single CLI and Loader are shared by all tests in a given class (or describe block).

Returns:



16
17
18
 
# File 'lib/toys/testing.rb', line 16

def toys_cli
  self.class.toys_cli
end