busser 0.9.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c0be7ee63d2b1d111438e2039187a5283308daae897a27d6028c08d9cefa13d
-  data.tar.gz: 49e9d09408a9cc284cfb9b43f8daeac1f55eda961ad66697dbefe8741ce2976a
+  metadata.gz: cdaf83b2875620df49aa36203b6d4f7f2f6af8065ecbaa218705c949fa96fe04
+  data.tar.gz: 40471ed874096d5b55bb8c613a33a7729e761d691f6727e4a848edf0fe398dbd
 SHA512:
-  metadata.gz: 71b525573141abe2bf35be2559189a811328e608eaef9a1ead8390595b7d500e76344ef7d29c624028c42d3e7a288a23c41e2e4a09d288734101ee9de2975d35
-  data.tar.gz: 4d769038c5032cfefdc0b50217f77e6950d2121162c4a07bdbd7d3a7a4b1b794d35a7d501b94ad5621c7628e942cd8d4f56c90d87fa01d0e7aab722e0961fd54
+  metadata.gz: 01b77c64592e8bed4f630149be35b89e5b3ac9935119f0c62216b5c16c0ae32ef3feb75c61d68ddf1127ea7bafff7de31f5d11297f2498501d9641b74eab163d
+  data.tar.gz: 8efbe414c2a434a98ff91be2f368bd2811cf8110bfce65c337859fbe3806ddca29751f9969a1fa9718c75b8ced4b92176ee33b137bf93b2046cace29fe77f0f6

data/.github/workflows/publish.yml

@@ -43,3 +43,25 @@ jobs:
         uses: actionshub/publish-gem-to-rubygems@f9126f7a2d36a4fd31a13e78fde5fbdcc4b7b251  # v2.0.6
         with:
           token: ${{ secrets.RUBYGEMS_API_KEY }}
+
+      # actionshub/publish-gem-to-rubygems logs a rejected push and still exits
+      # 0, so a release that never reached RubyGems shows up as a green job.
+      # Ask RubyGems directly instead of trusting the step. The v2 endpoint is
+      # 404 until the exact version is indexed, so -f turns "not there" into a
+      # non-zero exit rather than a substring match on `gem list` output.
+      - name: Verify the release reached RubyGems
+        if: ${{ steps.release.outputs.release_created }}
+        env:
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          set -euo pipefail
+          name="$(basename "$(ls ./*.gemspec)" .gemspec)"
+          for _ in $(seq 1 12); do
+            if curl -fsS -o /dev/null "https://rubygems.org/api/v2/rubygems/${name}/versions/${VERSION}.json"; then
+              echo "${name} ${VERSION} is on RubyGems"
+              exit 0
+            fi
+            sleep 15
+          done
+          echo "::error::${name} ${VERSION} never reached RubyGems. A permissions failure in the push step above does not fail that step -- read its log."
+          exit 1

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.9.1"
+  ".": "0.9.2"
 }

data/.rubocop.yml

@@ -3,7 +3,4 @@ require:
   - cookstyle/chefstyle
 
 AllCops:
-  TargetRubyVersion: 3.1
-  Exclude:
-    - "vendor/**/*"
-    - "spec/**/*"
+  TargetRubyVersion: 3.2

data/CHANGELOG.md

@@ -33,6 +33,16 @@ main reason to take this version.
 * Rewritten README, and development documentation moved to
   CONTRIBUTING.md ([#63](https://github.com/test-kitchen/busser/pull/63))
 
+## [0.9.2](https://github.com/test-kitchen/busser/compare/v0.9.1...v0.9.2) (2026-08-28)
+
+
+### Bug Fixes
+
+* quote the prepare.sh path before handing it to a shell ([#73](https://github.com/test-kitchen/busser/issues/73)) ([00a24a4](https://github.com/test-kitchen/busser/commit/00a24a4d4c286f50ac698b2cda9e9600b1c54322))
+* restore SSL verification if a plugin postinstall raises ([#72](https://github.com/test-kitchen/busser/issues/72)) ([7f26adb](https://github.com/test-kitchen/busser/commit/7f26adbca1682bd152afb8fc15d90feb55c15d8e))
+* stop `busser plugin list` printing git errors and a phantom plugin ([#77](https://github.com/test-kitchen/busser/issues/77)) ([7a99ebd](https://github.com/test-kitchen/busser/commit/7a99ebd8453ddc836bc0abf0af0f639f07b8d554))
+* tell Thor to exit non-zero when a command fails ([#76](https://github.com/test-kitchen/busser/issues/76)) ([218ba31](https://github.com/test-kitchen/busser/commit/218ba31b812db55cba2479ba6345d305743cb0c1))
+
 ## [0.9.1](https://github.com/test-kitchen/busser/compare/v0.9.0...v0.9.1) (2026-08-28)
 
 

data/Gemfile

@@ -1,13 +1,20 @@
 source "https://rubygems.org"
 
-gemspec development_group: :test
+gemspec
+
 group :cookstyle do
-  gem "cookstyle"
+  gem "cookstyle", ">= 9.0"
 end
 
 group :test do
-  gem "minitest", ">= 6.0"
-  gem "base64" # cucumber needs it; not a default gem on Ruby 4.0
+  gem "aruba", ">= 2.4"
+  gem "base64", ">= 0.3" # cucumber needs it; not a default gem on Ruby 4.0
   gem "cucumber", ">= 11.1"
-  gem "rake"
+  gem "minitest", ">= 6.0"
+  gem "mocha", ">= 2.7"
+  gem "rake", ">= 13.4"
+end
+
+group :development do
+  gem "yard", ">= 0.9.37"
 end

data/README.md

@@ -87,6 +87,88 @@ busser test
 busser test bash minitest
 ```
 
+## Using Busser with Test Kitchen
+
+This is how most people meet Busser, and it needs no `busser` commands of your
+own. Select the verifier in `kitchen.yml`:
+
+```yaml
+verifier:
+  name: busser
+
+suites:
+  - name: default
+```
+
+Then put tests in a directory named after the plugin that should run them,
+inside the suite:
+
+```text
+test/integration/default/bash/smoke_test.sh
+```
+
+`kitchen verify` installs Busser and the matching plugin on the instance, then
+runs the suite. Which plugin runs is decided by that directory name alone --
+`bash/` is picked up by busser-bash, `minitest/` by busser-minitest, and so on.
+There is nothing else to configure.
+
+## A worked example, without Test Kitchen
+
+To see Busser on its own, set a `BUSSER_ROOT` you can write to:
+
+```bash
+export BUSSER_ROOT=/tmp/busser
+busser setup
+busser plugin install busser-bash
+mkdir -p "$BUSSER_ROOT/suites/bash"
+
+cat > "$BUSSER_ROOT/suites/bash/smoke_test.sh" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+echo hello
+SH
+
+busser test bash
+```
+
+A passing run looks like this, and exits `0`:
+
+```text
+-----> Running bash test suite
+-----> [bash] smoke_test.sh
+hello
+```
+
+A failing one names the command and exits non-zero:
+
+```text
+-----> Running bash test suite
+-----> [bash] smoke_test.sh
+!!!!!! Command [bash /tmp/busser/suites/bash/smoke_test.sh] exit code was 1
+```
+
+## When nothing runs
+
+A suite whose files do not match what the plugin looks for produces this, and
+**exits `0`**:
+
+```text
+-----> Running bash test suite
+```
+
+No tests ran, and nothing said so. If a suite looks like it is being skipped,
+work through these in order:
+
+1. **Is the plugin installed?** `busser plugin list` shows what is available.
+   Without the plugin, `busser test` has no runner for that directory.
+2. **Is the directory named after the plugin?** Tests for busser-bash live in
+   `bash/`, not `tests/` or `scripts/`.
+3. **Do the filenames match?** Each plugin globs for its own pattern -- for
+   example busser-bash takes `*_test.sh` and `*_spec.bash` but ignores
+   `mytest.sh`. Each plugin's README states its pattern.
+4. **Is `BUSSER_ROOT` what you think?** `busser suite path` prints where suites
+   are actually being looked for.
+
 ## Contributing
 
 Bug reports and pull requests are welcome. See

data/Rakefile

@@ -9,7 +9,25 @@ Rake::TestTask.new(:unit) do |t|
 end
 
 Cucumber::Rake::Task.new(:features) do |t|
-  t.cucumber_opts = ["features", "-x", "--format progress", "--no-color", "-b"]
+  t.cucumber_opts = ["features", "--format progress", "--fail-fast"]
+end
+
+# yard lives in the :development group, which CI omits when it runs the tests.
+# Requiring it unconditionally would make `rake test` fail there, so the real
+# task is only defined when yard is installed and a stub explains its absence
+# otherwise. Nothing in CI gates on documentation.
+begin
+  require "yard"
+
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files = ["lib/**/*.rb"]
+    t.options = ["--output-dir", "doc", "--markup", "markdown"]
+  end
+rescue LoadError
+  desc "Generate YARD documentation (install the development group first)"
+  task :doc do
+    abort "yard is not available. Run `bundle install --with development` first."
+  end
 end
 
 desc "Run all test suites"

data/busser.gemspec

@@ -7,25 +7,28 @@ Gem::Specification.new do |spec|
   spec.version       = Busser::VERSION
   spec.authors       = ["Fletcher Nichol"]
   spec.email         = ["fnichol@nichol.ca"]
-  spec.description   = %q{Busser - Runs tests for projects in Test Kitchen}
+  spec.description   = "Busser - Runs tests for projects in Test Kitchen"
   spec.summary       = spec.description
   spec.homepage      = "https://github.com/test-kitchen/busser"
   spec.license       = "Apache-2.0"
 
-  spec.files         = `git ls-files`.split($/)
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 3.2"
+  spec.metadata = {
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "#{spec.homepage}/blob/main/README.md",
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+  }
 
   # thor 1.1.0 references DidYouMean::SPELL_CHECKERS, removed in Ruby 3.1,
   # so the CLI crashed on startup on every supported Ruby
   spec.add_dependency "thor", ">= 1.1"
   # base64 is no longer a default gem; deserialize needs it at runtime
   spec.add_dependency "base64"
-
-  spec.add_development_dependency "aruba", ">= 2.0"
-  spec.add_development_dependency "minitest"
-  spec.add_development_dependency "mocha"
-  spec.add_development_dependency "rake"
 end

data/lib/busser/command/deserialize.rb

@@ -38,6 +38,10 @@ module Busser
 
       class_option :perms, desc: "Unix permissions on destination file"
 
+      # Writes a file that was streamed in over stdin, checking it arrived
+      # intact before applying its permissions.
+      #
+      # @return [void]
       def perform
         file = File.expand_path(options[:destination])
         contents = Base64.decode64(STDIN.read)

data/lib/busser/command/plugin_create.rb

@@ -36,6 +36,9 @@ module Busser
       class_option :license, aliases: "-l", default: "apachev2",
         desc: "License type for gem (apachev2, mit, lgplv3, reserved)"
 
+      # Generates a new runner plugin project.
+      #
+      # @return [void]
       def create
         self.class.source_root(Busser.source_root.join("templates", "plugin"))
 
@@ -47,6 +50,9 @@ module Busser
 
       private
 
+      # Writes the gemspec, Gemfile, Rakefile, README and licence.
+      #
+      # @return [void]
       def create_core_files
         empty_directory(target_dir)
 
@@ -60,6 +66,9 @@ module Busser
         create_template("github_workflow.yml.erb", ".github/workflows/test.yml")
       end
 
+      # Writes lib/, the version file and the runner plugin class.
+      #
+      # @return [void]
       def create_source_files
         empty_directory(File.join(target_dir, "lib/busser", name))
         empty_directory(File.join(target_dir, "lib/busser/runner_plugin"))
@@ -74,6 +83,9 @@ module Busser
         )
       end
 
+      # Writes a starter cucumber suite for the new plugin.
+      #
+      # @return [void]
       def create_features_files
         empty_directory(File.join(target_dir, "features/support"))
 
@@ -95,6 +107,10 @@ module Busser
         )
       end
 
+      # Runs git init in the generated project, so the gemspec's
+      # `git ls-files` has something to read.
+      #
+      # @return [void]
       def initialize_git
         inside(target_dir) do
           run("git init")
@@ -102,14 +118,21 @@ module Busser
         end
       end
 
+      # @param erb [String] template path, relative to the templates directory
+      # @param dest [String] destination path, relative to the target directory
+      # @return [void]
       def create_template(erb, dest)
         template(erb, File.join(target_dir, dest), config)
       end
 
+      # @return [String] directory the new plugin is generated into
       def target_dir
         File.join(Dir.pwd, "busser-#{name}")
       end
 
+      # Values the templates interpolate.
+      #
+      # @return [Hash] the template binding
       def config
         @config ||= begin
           type_klass_name = "#{::Thor::Util.camel_case(options[:type])}Plugin"
@@ -132,16 +155,19 @@ module Busser
         end
       end
 
+      # @return [String] the author name, from git config where available
       def author
         git_user_name = `git config user.name`.chomp
         git_user_name.empty? ? "TODO: Write your name" : git_user_name
       end
 
+      # @return [String] the author email, from git config where available
       def email
         git_user_email = `git config user.email`.chomp
         git_user_email.empty? ? "TODO: Write your email" : git_user_email
       end
 
+      # @return [String] full licence text for the chosen licence
       def license_string
         case options[:license]
         when "mit" then "MIT"
@@ -168,6 +194,8 @@ module Busser
         end
       end
 
+      # @return [String] the filename the licence is written to, which differs
+      #   by licence
       def license_filename
         case options[:license]
         when "mit" then "LICENSE.txt"
@@ -178,6 +206,7 @@ module Busser
         end
       end
 
+      # @return [String] the licence header comment prepended to source files
       def license_comment
         @license_comment ||= IO.read(File.join(target_dir, license_filename))
           .gsub(/^/, "# ").gsub(/\s+$/, "")

data/lib/busser/command/plugin_install.rb

@@ -40,6 +40,9 @@ module Busser
       class_option :verbose, type: :boolean, default: false,
         desc: "Set a more verbose output"
 
+      # Installs each requested plugin.
+      #
+      # @return [void]
       def install_all
         if options[:verbose]
           Gem.configuration.verbose = 2 if options[:verbose]
@@ -53,6 +56,10 @@ module Busser
 
       private
 
+      # Installs one plugin and runs its postinstall.
+      #
+      # @param plugin [String] gem name, optionally suffixed with @version
+      # @return [void]
       def install(plugin)
         gem_name, version = plugin.split("@")
         name = gem_name.sub(/^busser-/, "")
@@ -65,6 +72,12 @@ module Busser
         end
       end
 
+      # Installs the plugin gem unless it is already available.
+      #
+      # @param gem [String] the gem name
+      # @param version [String, nil] a version requirement, or nil for any
+      # @param name [String] short plugin name, for the message
+      # @return [Boolean] true if the gem was newly installed
       def install_plugin_gem(gem, version, name)
         if internal_plugin?(name) || gem_installed?(gem, version)
           info "Plugin #{name} already installed"
@@ -76,10 +89,17 @@ module Busser
         end
       end
 
+      # @param name [String] short plugin name
+      # @return [void]
       def load_plugin(name)
         Busser::Plugin.require!(Busser::Plugin.runner_plugin(name))
       end
 
+      # Runs the plugin's postinstall block, which is where a plugin installs
+      # the test framework it drives.
+      #
+      # @param name [String] short plugin name
+      # @return [void]
       def run_postinstall(name)
         klass = Busser::Plugin.runner_class(::Thor::Util.camel_case(name))
         if klass.respond_to?(:run_postinstall)
@@ -100,13 +120,29 @@ module Busser
       #
       # Please use with extreme caution.
       #
+      # The restore is in an ensure block. Without one, a postinstall that
+      # raised left VERIFY_PEER set to VERIFY_NONE for the rest of the
+      # process -- and `busser plugin install` takes a list, so every gem
+      # downloaded for every later plugin in that same run would have had its
+      # certificate unchecked.
+      #
+      # @yield the block to run with peer verification dropped
+      # @return [void]
       def drop_ssl_verify_peer
         before = OpenSSL::SSL::VERIFY_PEER
+        set_ssl_verify_peer(OpenSSL::SSL::VERIFY_NONE)
+        begin
+          yield
+        ensure
+          set_ssl_verify_peer(before)
+        end
+      end
+
+      # @param value [Integer] the OpenSSL verify mode to install
+      # @return [void]
+      def set_ssl_verify_peer(value)
         OpenSSL::SSL.send(:remove_const, "VERIFY_PEER")
-        OpenSSL::SSL.const_set("VERIFY_PEER", OpenSSL::SSL::VERIFY_NONE)
-        yield
-        OpenSSL::SSL.send(:remove_const, "VERIFY_PEER")
-        OpenSSL::SSL.const_set("VERIFY_PEER", before)
+        OpenSSL::SSL.const_set("VERIFY_PEER", value)
       end
     end
   end

data/lib/busser/command/plugin_list.rb

@@ -28,6 +28,9 @@ module Busser
     #
     class PluginList < Busser::Thor::BaseGroup
 
+      # Prints the installed plugins and their versions.
+      #
+      # @return [void]
       def list
         if plugin_data.empty?
           say "No plugins installed yet"
@@ -38,11 +41,20 @@ module Busser
 
       private
 
+      # The dummy runner is a fixture shipped inside busser for its own tests,
+      # not something anyone installed. `busser test` already passes over it,
+      # so listing it as an installed plugin was inconsistent as well as
+      # confusing.
+      #
+      # @return [Array<Array(String, String)>] each installed plugin's short
+      #   name and version
       def plugin_data
-        @plugin_data ||= Busser::Plugin.runner_plugins.map do |path|
-          spec = Busser::Plugin.gem_from_path(path)
-          [File.basename(path), (spec && spec.version)]
-        end
+        @plugin_data ||= Busser::Plugin.runner_plugins
+          .reject { |path| File.basename(path) == "dummy" }
+          .map do |path|
+            spec = Busser::Plugin.gem_from_path(path)
+            [File.basename(path), (spec && spec.version)]
+          end
       end
     end
   end

data/lib/busser/command/setup.rb

@@ -32,6 +32,10 @@ module Busser
         desc: "Type of binstub file to create (bourne or bat)",
         default: "bourne"
 
+      # Creates the Busser root and the binstub that runs Busser with an
+      # isolated gem environment.
+      #
+      # @return [void]
       def perform
         banner "Setting up Busser"
         create_busser_root
@@ -40,11 +44,15 @@ module Busser
 
       private
 
+      # @return [void]
       def create_busser_root
         info "Creating BUSSER_ROOT in #{root_path}"
         empty_directory(root_path, verbose: false)
       end
 
+      # Writes the binstub, in whichever flavour --type asked for.
+      #
+      # @return [void]
       def generate_busser_binstub
         info "Creating busser binstub"
 
@@ -55,6 +63,9 @@ module Busser
         end
       end
 
+      # Writes a Windows batch binstub.
+      #
+      # @return [void]
       def generate_busser_binstub_for_bat
         binstub = root_path + "bin/busser.bat"
         busser_root = root_path.to_s.gsub("/", "\\")
@@ -105,6 +116,9 @@ module Busser
         end
       end
 
+      # Writes a Bourne shell binstub, executable.
+      #
+      # @return [void]
       def generate_busser_binstub_for_bourne
         binstub = root_path + "bin/busser"
 
@@ -144,6 +158,8 @@ module Busser
         chmod(binstub, 0755, verbose: false)
       end
 
+      # @return [String] path to the Ruby that is running Busser, in the path
+      #   style the target binstub needs
       def ruby_bin
         result = if (bindir = RbConfig::CONFIG["bindir"])
                    File.join(bindir, "ruby")
@@ -154,18 +170,22 @@ module Busser
         result
       end
 
+      # @return [String] the isolated gem home the binstub exports
       def gem_home
         Gem.paths.home.dup.tap { |p| p.gsub!("/", "\\") if bat? }
       end
 
+      # @return [String] the gem path the binstub exports
       def gem_path
         Gem.paths.path.join(":").dup.tap { |p| p.gsub!("/", "\\") if bat? }
       end
 
+      # @return [String] directory holding the real busser executable
       def gem_bindir
         Gem.bindir.dup.tap { |p| p.gsub!("/", "\\") if bat? }
       end
 
+      # @return [Boolean] true when generating a Windows batch binstub
       def bat?
         options[:type] == "bat"
       end

data/lib/busser/command/suite_cleanup.rb

@@ -28,6 +28,9 @@ module Busser
     #
     class SuiteCleanup < Busser::Thor::BaseGroup
 
+      # Removes the suites directory and everything in it.
+      #
+      # @return [void]
       def cleanup
         if suite_path.directory?
           Pathname.glob(suite_path + "*").each do |dir|

data/lib/busser/command/suite_path.rb

@@ -29,6 +29,9 @@ module Busser
 
       argument :suite_name, required: false
 
+      # Prints where suites live, or where one named suite lives.
+      #
+      # @return [void]
       def path
         say suite_path(suite_name).to_s
       end

data/lib/busser/command/test.rb

@@ -15,11 +15,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "shellwords" unless defined?(Shellwords)
+
 require "busser/thor"
 require "busser/plugin"
 
 module Busser
 
+  # Namespace for Busser's subcommands.
   module Command
 
     # Test command.
@@ -30,6 +33,10 @@ module Busser
 
       argument :plugins, type: :array, required: false
 
+      # Runs each requested plugin's suite, or every installed plugin's suite
+      # when none were named.
+      #
+      # @return [void]
       def perform
         Busser::Plugin.runner_plugins(plugins).each do |runner_path|
           runner = File.basename(runner_path)
@@ -44,26 +51,56 @@ module Busser
         end
       end
 
+      # Builds the command that runs a suite's prepare.sh.
+      #
+      # The path is quoted. It is rooted at BUSSER_ROOT, which the caller
+      # chooses, so an unquoted path containing a space would be split by the
+      # shell and sh would be handed a fragment instead of the script.
+      #
+      # @param script [String, Pathname] path to the prepare.sh
+      # @return [String] the command to run
+      def self.prepare_sh_command(script)
+        "/bin/sh #{Shellwords.escape(script.to_s)}"
+      end
+
       private
 
+      # The dummy runner exists for Busser's own tests, so it only runs when
+      # asked for by name.
+      #
+      # @param runner [String] short plugin name
+      # @return [Boolean] true if this runner should be passed over
       def skip_runner?(runner)
         runner == "dummy" && ! Array(plugins).include?("dummy")
       end
 
+      # Runs whatever preparation the suite ships before its tests.
+      #
+      # @param runner [String] short plugin name
+      # @return [void]
       def prepare_suite(runner)
         run_prepare_sh(runner)
         run_prepare_recipe(runner)
       end
 
+      # Runs the suite's prepare.sh, if it has one.
+      #
+      # @param runner [String] short plugin name
+      # @return [void]
       def run_prepare_sh(runner)
         prepare_sh_script = suite_path(runner).join("prepare.sh")
 
         if prepare_sh_script.exist?
           banner "Preparing #{runner} suite with #{prepare_sh_script}"
-          run!("/bin/sh #{prepare_sh_script}")
+          run!(self.class.prepare_sh_command(prepare_sh_script))
         end
       end
 
+      # Warns if the suite still ships the prepare_recipe.rb that Busser
+      # dropped support for, rather than ignoring it silently.
+      #
+      # @param runner [String] short plugin name
+      # @return [void]
       def run_prepare_recipe(runner)
         prepare_recipe = suite_path(runner).join("prepare_recipe.rb")