busser 0.9.1 → 0.9.2

data/lib/busser/cucumber/hooks.rb

@@ -14,10 +14,19 @@ After do
   end
 end
 
+# Stashes an environment variable so a scenario can change it and have the
+# original put back afterwards.
+#
+# @param key [String] the variable name
+# @return [String, nil] the stashed value
 def backup_envvar(key)
   ENV["_CUKE_#{key}"] = ENV[key]
 end
 
+# Puts back a variable stashed by {backup_envvar}.
+#
+# @param key [String] the variable name
+# @return [String, nil] the restored value
 def restore_envvar(key)
   ENV[key] = ENV.delete("_CUKE_#{key}")
 end

data/lib/busser/helpers.rb

@@ -29,22 +29,41 @@ module Busser
 
     module_function
 
+    # Path to the suites directory, or to one suite inside it.
+    #
+    # @param name [String, nil] a suite name, or nil for the containing
+    #   directory
+    # @return [Pathname] absolute path beneath the Busser root
     def suite_path(name = nil)
       path = root_path + "suites"
       path += name if name
       path.expand_path
     end
 
+    # Path to the vendor directory, or to one vendored product inside it.
+    #
+    # @param product [String, nil] a product name, or nil for the containing
+    #   directory
+    # @return [Pathname] absolute path beneath the Busser root
     def vendor_path(product = nil)
       path = root_path + "vendor"
       path += product if product
       path.expand_path
     end
 
+    # The Busser root, where plugins, suites and vendored products live.
+    #
+    # @return [Pathname] BUSSER_ROOT if set, otherwise /opt/busser
     def root_path
       Pathname.new(ENV["BUSSER_ROOT"] || "/opt/busser")
     end
 
+    # No longer supported. Kept so a plugin still calling it warns rather
+    # than dying with a NoMethodError halfway through a test run.
+    #
+    # @param config [Hash] ignored
+    # @return [void]
+    # @deprecated Shell out or use a Thor action instead.
     def chef_apply(config = {}, &block)
       warn "Apologies, but Busser no longer supports the chef_apply helper," +
         " so the contents of this block will not be executed. Please refactor" +
@@ -52,6 +71,11 @@ module Busser
         " strategy"
     end
 
+    # Installs a gem into the Busser root's gem home.
+    #
+    # @param gem [String] the gem name
+    # @param version [String, nil] a requirement string, or nil for any version
+    # @return [Gem::Specification, nil] the spec that was installed
     def install_gem(gem, version = nil)
       Busser::RubyGems.install_gem(gem, version)
     end

data/lib/busser/plugin.rb

@@ -17,6 +17,7 @@
 
 module Busser
 
+  # Namespace that runner plugins define their classes inside.
   module RunnerPlugin
   end
 
@@ -28,10 +29,17 @@ module Busser
 
     module_function
 
+    # @param plugin_name [String] short plugin name, such as "bash"
+    # @return [String] the path to require for that plugin
     def runner_plugin(plugin_name)
       "busser/runner_plugin/#{plugin_name}"
     end
 
+    # Require paths for the named plugins, or for every installed plugin.
+    #
+    # @param plugin_names [Array<String>, String, nil] plugin names, or nil for
+    #   everything installed
+    # @return [Array<String>] require paths, without duplicates
     def runner_plugins(plugin_names = nil)
       if plugin_names
         Array(plugin_names).map { |plugin| runner_plugin(plugin) }.uniq
@@ -46,33 +54,67 @@ module Busser
     # duplicates made `busser test` run a suite twice and `busser plugin list`
     # print it twice. The path is what gets required, and require resolves to
     # the active version, so collapsing the repeats is safe.
+    # Require paths for every runner plugin installed on this machine.
+    #
+    # @return [Array<String>] require paths, without duplicates
     def all_runner_plugins
       Gem.find_files("busser/runner_plugin/*.rb").map do |file|
         "busser/runner_plugin/#{File.basename(file).sub(/\.rb$/, "")}"
       end.uniq
     end
 
+    # Requires a plugin, exiting with a readable message rather than a
+    # backtrace if it cannot be loaded.
+    #
+    # @param plugin_path [String] the path to require
+    # @return [void]
     def require!(plugin_path)
       require plugin_path
     rescue LoadError => e
       Busser::UI.die "Could not load #{plugin_path} (#{e.class}: #{e.message})"
     end
 
+    # @param klass [String, Symbol] a constant name inside
+    #   {Busser::RunnerPlugin}
+    # @return [Class] the runner plugin class
     def runner_class(klass)
       Busser::RunnerPlugin.const_get(klass)
     end
 
+    # Finds the gemspec a plugin was loaded from.
+    #
+    # A plugin being developed locally is not an installed gem, so the local
+    # gemspec is preferred when the plugin resolves inside the working tree.
+    #
+    # @param plugin_path [String] the plugin's require path
+    # @return [Gem::Specification] the spec the plugin belongs to
     def gem_from_path(plugin_path)
-      local_gem_path = "#{File.expand_path(plugin_path, $LOAD_PATH.first)}"
-      local_gemspec = File.join(
-        File.dirname($LOAD_PATH.first), "busser.gemspec"
-      )
+      # Ask RubyGems first. Loading a gemspec *evaluates* it, and these
+      # gemspecs shell out to `git ls-files` to build their file list -- so
+      # asking the working tree first printed "fatal: not a git repository"
+      # into the middle of `busser plugin list` for every installed plugin.
+      # find_by_path answers from the installed specs without running anything.
+      Gem::Specification.find_by_path(plugin_path) ||
+        local_gemspec_for(plugin_path)
+    end
 
-      if ! Dir.glob("#{local_gem_path}#{Gem.suffix_pattern}").empty?
-        Gem::Specification.load(File.expand_path(local_gemspec))
-      else
-        Gem::Specification.find_by_path(plugin_path)
-      end
+    # Falls back to a gemspec in the working tree, which is how a plugin being
+    # developed locally -- and so not installed as a gem -- is resolved.
+    #
+    # @param plugin_path [String] the plugin's require path
+    # @return [Gem::Specification, nil] the spec, or nil if there is no local
+    #   gemspec to read
+    def local_gemspec_for(plugin_path)
+      root = $LOAD_PATH.first
+      return nil if root.nil?
+
+      local_gem_path = File.expand_path(plugin_path, root)
+      return nil if Dir.glob("#{local_gem_path}#{Gem.suffix_pattern}").empty?
+
+      local_gemspec = File.join(File.dirname(root), "busser.gemspec")
+      return nil unless File.exist?(local_gemspec)
+
+      Gem::Specification.load(local_gemspec)
     end
   end
 end

data/lib/busser/rubygems.rb

@@ -27,11 +27,24 @@ module Busser
 
     module_function
 
+    # @param name [String] the gem name
+    # @param version [String, nil] a requirement string, or nil for any version
+    # @return [Boolean] true if a matching gem is already available
     def gem_installed?(name, version)
       version = Gem::Requirement.default unless version
       ! Gem::Dependency.new(name, version).matching_specs.empty?
     end
 
+    # Installs a gem into GEM_HOME.
+    #
+    # RubyGems under bundler points Gem.dir at the bundle, which is not where
+    # Busser plugins belong, so GEM_HOME is applied explicitly before the
+    # install and the freshly installed spec is put on the load path by hand.
+    #
+    # @param gem_name [String] the gem name
+    # @param version [String, nil] a requirement string, or nil for any version
+    # @return [Gem::Specification, nil] the installed spec, or nil if the gem
+    #   was not among those installed
     def install_gem(gem_name, version)
       version = Gem::Requirement.default unless version
 
@@ -54,6 +67,8 @@ module Busser
       spec
     end
 
+    # @return [Hash] options handed to RubyGems' dependency installer, with
+    #   the install directory pinned to GEM_HOME
     def rbg_options
       @rbg_options ||= Gem::DependencyInstaller::DEFAULT_OPTIONS.merge(
         suggest_alternate: false,
@@ -67,6 +82,11 @@ module Busser
       )
     end
 
+    # Runs a block with RubyGems' own progress output suppressed, unless the
+    # user asked for verbose output.
+    #
+    # @yield the block to run quietly
+    # @return [Object] whatever the block returned
     def silence_gem_ui
       interaction = Gem::DefaultUserInteraction.ui
       unless Gem.configuration.really_verbose

data/lib/busser/runner_plugin/dummy.rb

@@ -34,6 +34,9 @@ class Busser::RunnerPlugin::Dummy < Busser::RunnerPlugin::Base
     create_file("#{dummy_path}/foobar.txt", "The Dummy Driver.")
   end
 
+  # Prints a line so Busser's own suite can prove a plugin ran.
+  #
+  # @return [void]
   def test
     banner "[dummy] Running"
     if File.exist?(File.join(suite_path("dummy"), "foobar.txt"))

data/lib/busser/runner_plugin.rb

@@ -27,6 +27,11 @@ module Busser
     #
     class Base < Busser::Thor::BaseGroup
 
+      # Declares work to run once, when Busser installs this plugin -- which
+      # is where a plugin installs the test framework it drives.
+      #
+      # @yield the postinstall body, evaluated on the plugin instance
+      # @return [void]
       def self.postinstall(&block)
         (class << self; self; end).send(:define_method, :run_postinstall) do
           klass = Class.new(Busser::Thor::BaseGroup) do

data/lib/busser/thor.rb

@@ -22,6 +22,7 @@ require "busser/ui"
 
 module Busser
 
+  # Thor base classes preloaded with Busser's helpers and output methods.
   module Thor
 
     # Base class for all Thor subclasses which includes useful mixins.
@@ -33,6 +34,17 @@ module Busser
       include Helpers
       include UI
       include ::Thor::Actions
+
+      # Thor exits 0 when a command fails unless this is true, and warns on
+      # every failure that it is not set. Busser is a test runner: a failure
+      # has to be a non-zero exit or CI reports a red suite as green. Thor 2
+      # makes this the default; setting it now silences the deprecation on
+      # every failing run and pins the behaviour we already rely on.
+      #
+      # @return [true]
+      def self.exit_on_failure?
+        true
+      end
     end
 
     # Base class for all Thor Group subclasses which includes useful mixins.
@@ -44,6 +56,17 @@ module Busser
       include Helpers
       include UI
       include ::Thor::Actions
+
+      # Thor exits 0 when a command fails unless this is true, and warns on
+      # every failure that it is not set. Busser is a test runner: a failure
+      # has to be a non-zero exit or CI reports a red suite as green. Thor 2
+      # makes this the default; setting it now silences the deprecation on
+      # every failing run and pins the behaviour we already rely on.
+      #
+      # @return [true]
+      def self.exit_on_failure?
+        true
+      end
     end
   end
 end

data/lib/busser/ui.rb

@@ -29,30 +29,56 @@ module Busser
 
     # Thor::Shell's delegated methods are not mixed into this module, so
     # provide the two output primitives it relies on.
+    # @param msg [String] text to write to stdout
+    # @return [void]
     def say(msg)
       $stdout.puts(msg)
     end
 
+    # @param msg [String] text to write to stderr
+    # @return [void]
     def error(msg)
       $stderr.puts(msg)
     end
 
+    # Announces a step, at the top level of the output.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def banner(msg)
       say("-----> #{msg}")
     end
 
+    # Reports detail beneath a banner.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def info(msg)
       say("       #{msg}")
     end
 
+    # Reports something the user should notice but which is not fatal.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def warn(msg)
       say(">>>>>> #{msg}")
     end
 
+    # Reports a failure, on stderr.
+    #
+    # @param msg [String] the message
+    # @return [void]
     def fatal(msg)
       error("!!!!!! #{msg}")
     end
 
+    # Runs a shell command, exiting with a diagnosis if it fails.
+    #
+    # @param cmd [String] the command line
+    # @param config [Hash] options passed through to Thor's runner
+    # @return [true] if the command succeeded
+    # @see #handle_command
     def run!(cmd, config = {})
       config = { capture: false, verbose: false }.merge(config)
 
@@ -61,6 +87,13 @@ module Busser
       end
     end
 
+    # Runs a Ruby script with the current interpreter, exiting with a
+    # diagnosis if it fails.
+    #
+    # @param cmd [String] the script and its arguments
+    # @param config [Hash] options passed through to Thor's runner
+    # @return [true] if the script succeeded
+    # @see #handle_command
     def run_ruby_script!(cmd, config = {})
       config = { capture: false, verbose: false }.merge(config)
 
@@ -69,15 +102,37 @@ module Busser
       end
     end
 
+    # Reports a failure and exits.
+    #
+    # @param msg [String] the message
+    # @param exitstatus [Integer] the status to exit with
+    # @return [void] does not return
     def die(msg, exitstatus = 1)
       fatal(msg)
       exit(exitstatus)
     end
 
+    # Wrapped so tests can stub it.
+    #
+    # @return [Process::Status, nil] the status of the last child process
     def status
       $?
     end
 
+    # Runs a block and turns however the child process ended into a readable
+    # message and a matching exit status.
+    #
+    # Three endings are distinguished because they mean different things to
+    # someone reading CI output: a nil status usually means the machine ran out
+    # of memory before the child could report; a signal means something killed
+    # the run, typically the out of memory killer; and an exit code means the
+    # command itself failed.
+    #
+    # @param type [String] what was run, for the message
+    # @param cmd [String] the command line, for the message
+    # @yield runs the command
+    # @return [true] if the command succeeded
+    # @raise [StandardError] re-raised if the block itself raised
     def handle_command(type, cmd)
       begin
         yield

data/lib/busser/version.rb

@@ -16,5 +16,6 @@
 # limitations under the License.
 
 module Busser
-  VERSION = "0.9.1".freeze
+  # Version string for Busser
+  VERSION = "0.9.2".freeze
 end

data/release-please-config.json

@@ -7,7 +7,9 @@
       "changelog-path": "CHANGELOG.md",
       "release-type": "ruby",
       "include-component-in-tag": false,
-      "version-file": "lib/busser/version.rb"
+      "version-file": "lib/busser/version.rb",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true
     }
   }
 }

data/spec/busser/command/deserialize_spec.rb

@@ -1,4 +1,3 @@
-# -*- encoding: utf-8 -*-
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/spec/busser/command/plugin_create_spec.rb

@@ -1,4 +1,3 @@
-# -*- encoding: utf-8 -*-
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/spec/busser/command/plugin_install_spec.rb

@@ -0,0 +1,44 @@
+require_relative "../../spec_helper"
+
+require "busser/command/plugin_install"
+
+describe Busser::Command::PluginInstall do
+  let(:command) { Busser::Command::PluginInstall.new([%w{busser-dummy}]) }
+
+  describe "#drop_ssl_verify_peer" do
+    # VERIFY_PEER is a process-global constant, so anything that leaves it
+    # lowered affects every later gem download in the same run. `busser plugin
+    # install` takes a list of plugins, which is exactly that situation.
+    it "lowers verification for the block" do
+      inside = nil
+      command.send(:drop_ssl_verify_peer) { inside = OpenSSL::SSL::VERIFY_PEER }
+
+      _(inside).must_equal OpenSSL::SSL::VERIFY_NONE
+    end
+
+    it "restores verification afterwards" do
+      before = OpenSSL::SSL::VERIFY_PEER
+      command.send(:drop_ssl_verify_peer) { nil }
+
+      _(OpenSSL::SSL::VERIFY_PEER).must_equal before
+    end
+
+    # The regression this guards. A postinstall raising is not exotic: it is
+    # how a plugin reports that it could not install its test framework.
+    it "restores verification when the block raises" do
+      before = OpenSSL::SSL::VERIFY_PEER
+
+      _(proc { command.send(:drop_ssl_verify_peer) { raise "postinstall blew up" } })
+        .must_raise RuntimeError
+
+      _(OpenSSL::SSL::VERIFY_PEER).must_equal before
+    end
+
+    it "restores verification when the block throws" do
+      before = OpenSSL::SSL::VERIFY_PEER
+      catch(:done) { command.send(:drop_ssl_verify_peer) { throw :done } }
+
+      _(OpenSSL::SSL::VERIFY_PEER).must_equal before
+    end
+  end
+end

data/spec/busser/command/plugin_list_spec.rb

@@ -0,0 +1,49 @@
+require_relative "../../spec_helper"
+
+require "busser/command/plugin_list"
+
+describe Busser::Command::PluginList do
+  let(:command) { Busser::Command::PluginList.new }
+
+  describe "#plugin_data" do
+    def stub_plugins(paths, specs = {})
+      Busser::Plugin.stubs(:runner_plugins).returns(paths)
+      paths.each do |path|
+        Busser::Plugin.stubs(:gem_from_path).with(path).returns(specs[path])
+      end
+    end
+
+    def spec_for(name, version)
+      Gem::Specification.new { |s| s.name = name; s.version = version }
+    end
+
+    it "reports each plugin's short name and version" do
+      stub_plugins(["busser/runner_plugin/bash"],
+        "busser/runner_plugin/bash" => spec_for("busser-bash", "0.2.0"))
+
+      _(command.send(:plugin_data)).must_equal [["bash", Gem::Version.new("0.2.0")]]
+    end
+
+    # dummy is a fixture shipped inside busser for its own tests, not something
+    # anyone installed. `busser test` already passes over it, so listing it was
+    # inconsistent as well as confusing.
+    it "leaves out the internal dummy runner" do
+      stub_plugins(["busser/runner_plugin/dummy", "busser/runner_plugin/bash"],
+        "busser/runner_plugin/bash" => spec_for("busser-bash", "0.2.0"))
+
+      _(command.send(:plugin_data).map(&:first)).must_equal %w{bash}
+    end
+
+    it "reports a nil version rather than raising when no spec is found" do
+      stub_plugins(["busser/runner_plugin/bash"])
+
+      _(command.send(:plugin_data)).must_equal [["bash", nil]]
+    end
+
+    it "returns an empty list when dummy is all there is" do
+      stub_plugins(["busser/runner_plugin/dummy"])
+
+      _(command.send(:plugin_data)).must_be_empty
+    end
+  end
+end

data/spec/busser/command/setup_spec.rb

@@ -1,4 +1,3 @@
-# -*- encoding: utf-8 -*-
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/spec/busser/command/test_spec.rb

@@ -0,0 +1,36 @@
+require_relative "../../spec_helper"
+
+require "shellwords"
+require "busser/command/test"
+
+describe Busser::Command::Test do
+  describe ".prepare_sh_command" do
+    it "runs the script with sh" do
+      cmd = Busser::Command::Test.prepare_sh_command("/opt/busser/suites/bats/prepare.sh")
+
+      _(Shellwords.split(cmd)).must_equal ["/bin/sh", "/opt/busser/suites/bats/prepare.sh"]
+    end
+
+    # BUSSER_ROOT is chosen by whoever runs Busser, and Test Kitchen puts it
+    # under a path the user controls. Unquoted, a space split the path and sh
+    # was handed a fragment.
+    it "quotes a path containing spaces" do
+      cmd = Busser::Command::Test.prepare_sh_command("/tmp/my tests/suites/bats/prepare.sh")
+
+      _(Shellwords.split(cmd))
+        .must_equal ["/bin/sh", "/tmp/my tests/suites/bats/prepare.sh"]
+    end
+
+    it "neutralises shell metacharacters in the path" do
+      cmd = Busser::Command::Test.prepare_sh_command("/tmp/a;touch pwned/prepare.sh")
+
+      _(Shellwords.split(cmd)).must_equal ["/bin/sh", "/tmp/a;touch pwned/prepare.sh"]
+    end
+
+    it "accepts a Pathname" do
+      cmd = Busser::Command::Test.prepare_sh_command(Pathname.new("/a/prepare.sh"))
+
+      _(Shellwords.split(cmd).last).must_equal "/a/prepare.sh"
+    end
+  end
+end

data/spec/busser/helpers_spec.rb

@@ -1,6 +1,6 @@
-require_relative '../spec_helper'
+require_relative "../spec_helper"
 
-require 'busser/helpers'
+require "busser/helpers"
 
 describe Busser::Helpers do
 
@@ -25,16 +25,16 @@ describe Busser::Helpers do
 
     describe "with a custom root path" do
 
-      before  { ENV['_SPEC_BUSSER_ROOT'] = ENV['BUSSER_ROOT'] }
-      after   { ENV['BUSSER_ROOT'] = ENV.delete('_SPEC_BUSSER_ROOT') }
+      before  { ENV["_SPEC_BUSSER_ROOT"] = ENV["BUSSER_ROOT"] }
+      after   { ENV["BUSSER_ROOT"] = ENV.delete("_SPEC_BUSSER_ROOT") }
 
       it "returns a base path if no suite name is given" do
-        ENV['BUSSER_ROOT'] = "/path/to/busser"
+        ENV["BUSSER_ROOT"] = "/path/to/busser"
         _(suite_path.to_s).must_match %r{/path/to/busser/suites$}
       end
 
       it "returns a suite path given a suite name" do
-        ENV['BUSSER_ROOT'] = "/path/to/busser"
+        ENV["BUSSER_ROOT"] = "/path/to/busser"
         _(suite_path("fuzzy").to_s).must_match %r{/path/to/busser/suites/fuzzy$}
       end
     end
@@ -59,16 +59,16 @@ describe Busser::Helpers do
 
     describe "with a custom root path" do
 
-      before  { ENV['_SPEC_BUSSER_ROOT'] = ENV['BUSSER_ROOT'] }
-      after   { ENV['BUSSER_ROOT'] = ENV.delete('_SPEC_BUSSER_ROOT') }
+      before  { ENV["_SPEC_BUSSER_ROOT"] = ENV["BUSSER_ROOT"] }
+      after   { ENV["BUSSER_ROOT"] = ENV.delete("_SPEC_BUSSER_ROOT") }
 
       it "returns a base path if no product name is given" do
-        ENV['BUSSER_ROOT'] = "/path/to/busser"
+        ENV["BUSSER_ROOT"] = "/path/to/busser"
         _(vendor_path.to_s).must_match %r{/path/to/busser/vendor$}
       end
 
       it "returns a suite path given a product name" do
-        ENV['BUSSER_ROOT'] = "/path/to/busser"
+        ENV["BUSSER_ROOT"] = "/path/to/busser"
         _(vendor_path("maximal").to_s).must_match \
           %r{/path/to/busser/vendor/maximal$}
       end

data/spec/busser/plugin_spec.rb

@@ -1,4 +1,3 @@
-# -*- encoding: utf-8 -*-
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/spec/busser/ui_spec.rb

@@ -1,6 +1,6 @@
-require_relative '../spec_helper'
+require_relative "../spec_helper"
 
-require 'busser/ui'
+require "busser/ui"
 
 # Dummy class containing diagnostic methods approximating Thor mixins
 class SneakyUI
@@ -11,7 +11,7 @@ class SneakyUI
   attr_accessor :status
 
   def say(msg)
-     msg
+    msg
   end
 
   def error(msg)
@@ -111,7 +111,7 @@ describe Busser::UI do
 
       _(ui.run_args).must_equal([
         "doitpls",
-        { :capture => false, :verbose => false}
+        { capture: false, verbose: false },
       ])
     end
 
@@ -181,16 +181,16 @@ describe Busser::UI do
 
       _(ui.run_ruby_script_args).must_equal([
         "theworks.rb",
-        { :capture => false, :verbose => false }
+        { capture: false, verbose: false },
       ])
     end
 
     it "calls #run_ruby_script with correct default options" do
-      ui.invoke_run_ruby_script!("theworks.rb", :verbose => true)
+      ui.invoke_run_ruby_script!("theworks.rb", verbose: true)
 
       _(ui.run_ruby_script_args).must_equal([
         "theworks.rb",
-        { :capture => false, :verbose => true }
+        { capture: false, verbose: true },
       ])
     end