module Toys::Testing

Helpers for writing tool tests.

EXPERIMENTAL: Interfaces are subject to change.

Public Class Methods

included(klass) click to toggle source

@private

# File lib/toys/testing.rb, line 170
def self.included(klass)
  klass.extend(ClassMethods)
end
toys_mutex() click to toggle source

@private

# File lib/toys/testing.rb, line 175
def self.toys_mutex
  @toys_mutex
end

Public Instance Methods

capture_separate_tool(cmd, **opts, &block) click to toggle source

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.

@param cmd [String,Array<String>] The command to execute. @param opts [keywords] The command options. @yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# 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, &block) click to toggle source

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}.

@param cmd [String,Array<String>] The command to execute. @param opts [keywords] The command options. @yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# 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, &block) click to toggle source

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.

@param cmd [String,Array<String>] The command to execute. @param opts [keywords] The command options. @yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# 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, &block) click to toggle source

Runs the tool corresponding to the given command line, provided as an array of arguments, in a separately spawned process, and returns a {Toys::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`.

@param cmd [String,Array<String>] The command to execute. @param opts [keywords] The command options. @yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# 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, &block) click to toggle source

Runs the tool corresponding to the given command line, provided as an array of arguments, and returns a {Toys::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}.

@param cmd [String,Array<String>] The command to execute. @param opts [keywords] The command options. @yieldparam controller [Toys::Utils::Exec::Controller] A controller

for the subprocess streams.

@return [Toys::Utils::Exec::Controller] The subprocess controller, if

the process is running in the background.

@return [Toys::Utils::Exec::Result] The result, if the process ran in

the foreground.
# 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() click to toggle source

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).

@return [Toys::CLI]

# File lib/toys/testing.rb, line 16
def toys_cli
  self.class.toys_cli
end