busser-bats 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b09420f04af698ba3b08210baee66053b30fb8ca42be2a96c2d6d0fa0b0af957
-  data.tar.gz: a997d8bec61c2d19360bc02474299d05145d0cabcc6719ddb51fb15b6e22751b
+  metadata.gz: 50827f7c53a1bce1a7ddc9bda08aacd3d7a2388fefc183b7bdc3cbdd23bac07f
+  data.tar.gz: 3a22e249cc415c99bdfd3f922b0a4d13665f267eb14216f2c1d226f76354ade3
 SHA512:
-  metadata.gz: 3ec7470327ddb5a43d1901b04ada64ff762c3a818e03fed8bf2d51dd539114c5311d8e3e72e3a94b967929daba61aca7251f49fbca0fbd041ff7d52b0a4ec18c
-  data.tar.gz: f803cb57196ba7cb19c386d080ef54cae9573227c8c34f834f1d1d6b2bfd9a8ff8754db592a4be907b24a83a5f36ab14ef309f7bc76bfe285731cd35e2ff932b
+  metadata.gz: c00aef02c07f8518d484107f04165d2e320cc0a822c36b7e74350795c84ce5e3b7d7a221cf75e0e679a9623995db2f2ee44a058b729a73a73442b8a56c38855f
+  data.tar.gz: 65749c81f7d399d2a2ce2c64eda0bc3235c815e7e1a7c6a2b0beef4756d8db414589140cdfc8df02d00da757d426eaf2f61bbcf3ab0c2cdb0f122401d96593fd

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/.gitignore

@@ -6,7 +6,6 @@
 Gemfile.lock
 InstalledFiles
 _yardoc
-coverage
 doc/
 lib/bundler/man
 pkg

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.0"
+  ".": "0.7.0"
 }

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # busser-bats Changelog
 
+## [0.7.0](https://github.com/test-kitchen/busser-bats/compare/v0.6.0...v0.7.0) (2026-08-28)
+
+
+### ⚠ BREAKING CHANGES
+
+* the vendored bats goes from 0.4.0 to 1.14.0. Suites relying on bats 0.4 behaviour may need updating; see the bats-core changelog.
+
+### Features
+
+* vendor bats-core instead of the archived sstephenson/bats ([#59](https://github.com/test-kitchen/busser-bats/issues/59)) ([377240c](https://github.com/test-kitchen/busser-bats/commit/377240cbf04dee7bdec158fc306bbc5a7e7fe509))
+
 ## [0.6.0](https://github.com/test-kitchen/busser-bats/compare/v0.5.0...v0.6.0) (2026-08-28)
 
 

data/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to busser-bats
+
+Thanks for taking the time to contribute. This document covers how to get the
+project running locally, how to check your work before opening a pull request,
+and the commit convention releases depend on.
+
+## Getting set up
+
+This plugin requires **Ruby 3.2 or newer**. Clone the repository and install the
+development dependencies:
+
+```bash
+git clone https://github.com/test-kitchen/busser-bats.git
+cd busser-bats
+bundle install
+```
+
+## Running the tests
+
+`rake` runs the whole suite:
+
+```bash
+bundle exec rake test
+```
+
+The tests are [cucumber](https://cucumber.io) features in `features/`. They
+drive the real `busser` executable through
+[aruba](https://github.com/cucumber/aruba) rather than calling the plugin's
+classes, so they cover it end to end: install the plugin into a throwaway
+Busser root, write a suite, run it, and check what came out. The step
+definitions they use are published by busser itself, in `lib/busser/cucumber.rb`.
+
+## Linting
+
+CI runs three linters, all of which you can run locally:
+
+```bash
+bundle exec cookstyle --chefstyle   # Ruby
+yamllint --strict .                 # YAML
+markdownlint-cli2 "**/*.md" "!**/CHANGELOG*.md"
+```
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org).
+Releases are automated, and the commit subject on `main` is what decides the
+next version number and what appears in the changelog.
+
+Pull requests are **squash merged, so the pull request title becomes that
+subject**. A CI check enforces the format on the title; the individual commits
+on your branch are not checked.
+
+| Prefix | Effect on the next release |
+| --- | --- |
+| `fix:` | Patch version bump |
+| `feat:` | Minor version bump |
+| `feat!:`, or a `BREAKING CHANGE:` footer | Minor bump, until this gem reaches 1.0 |
+| `chore:`, `docs:`, `ci:`, `test:`, `refactor:` | No release |
+
+For example:
+
+```text
+fix: install the plugin into GEM_HOME rather than the bundle
+feat: support a Gemfile alongside the suite
+ci: pin the shared workflow to a release
+```
+
+## Opening a pull request
+
+1. Fork the repository and create a branch for your change.
+2. Add or update tests. A bug fix should come with a test that fails without it.
+3. Run `bundle exec rake test` and the linters above.
+4. Open a pull request with a Conventional Commits title.
+
+## Releases
+
+Releases are handled by
+[release-please](https://github.com/googleapis/release-please). It watches
+commits landing on `main` and keeps a release pull request open with the next
+version number and the accumulated changelog. Merging that pull request tags the
+release and publishes the gem to RubyGems and GitHub Packages.
+
+Maintainers do not bump `lib/busser/bats/version.rb` or edit
+`CHANGELOG.md` by hand; release-please owns both files. This gem is still pre-1.0, so
+`bump-minor-pre-major` is set and a breaking change takes the minor rather than
+graduating it to 1.0.

data/Gemfile

@@ -3,16 +3,18 @@ source "https://rubygems.org"
 gemspec
 
 group :cookstyle do
-  gem "cookstyle", ">= 9.0.0"
+  gem "cookstyle", ">= 9.0"
 end
 
 group :test do
-  gem "aruba", ">= 2.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", ">= 11.0"
+  gem "minitest", ">= 6.0"
+  gem "mocha", ">= 2.7"
+  gem "rake", ">= 13.4"
 end
 
 group :development do
-  gem "simplecov"
+  gem "yard", ">= 0.9.37"
 end

data/README.md

@@ -1,50 +1,122 @@
-# Busser::RunnerPlugin::Bats
+# busser-bats
 
-[![Gem Version](https://badge.fury.io/rb/busser-bats.svg)](http://badge.fury.io/rb/busser-bats)
+[![Gem Version](https://badge.fury.io/rb/busser-bats.svg)](https://badge.fury.io/rb/busser-bats)
 
-A Busser runner plugin for [Bats][bats_site]
+A [Busser](https://github.com/test-kitchen/busser) runner plugin that runs
+[Bats](https://github.com/bats-core/bats-core) test files.
+
+Bats is a TAP-producing test harness for bash. This plugin vendors a copy of it,
+installs that copy onto the machine under test during postinstall, and then runs
+it against the suite's `bats` directory — so the machine under test needs
+nothing beyond bash.
+
+The vendored copy is [bats-core](https://github.com/bats-core/bats-core), which
+is the maintained fork; `vendor/bats/VERSION.txt` records the exact release.
+`rake bats:vendor` refreshes it, and `BATS_VERSION` selects a different tag.
 
 ## Status
 
-This software project is no longer under active development as it has no active maintainers. The software may continue to work for some or all use cases, but issues filed in GitHub will most likely not be triaged. If a new maintainer is interested in working on this project please come chat with us in #test-kitchen on Chef Community Slack.
+This software project is no longer under active development as it has no active
+maintainers. The software may continue to work for some or all use cases, but
+issues filed in GitHub will most likely not be triaged. If a new maintainer is
+interested in working on this project please come chat with us in #test-kitchen
+on Chef Community Slack.
+
+## Requirements
+
+Ruby 3.2 or newer, and busser 0.9.0 or newer.
+
+## Installation
 
-## Installation and Setup
+Busser installs the plugin for you when Test Kitchen runs the suite, so there is
+usually nothing to do. To install it by hand:
 
-Until proper reference documentation is complete, the [Writing a Test](https://kitchen.ci/docs/writing-test) section of the Test Kitchen's [Getting Started Guide](https://kitchen.ci/docs/) gives a working example of creating a bats test.
+```bash
+busser plugin install busser-bats
+```
 
 ## Usage
 
-**TODO:** Write documentation explaining the structure/format of testing files.
+Put your `.bats` files in the `bats` directory of a suite:
 
-## Development
+```text
+test
+`-- integration
+    `-- default          # suite name
+        `-- bats
+            `-- default.bats
+```
 
-* Source hosted at [GitHub][repo]
-* Report issues/questions/feature requests on [GitHub Issues][issues]
+The whole directory is handed to `bats`, which picks up every `*.bats` file in
+it. A test is a `@test` block, and it passes when every command in it succeeds:
 
-Pull requests are very welcome! Make sure your patches are well tested.
-Ideally create a topic branch for every separate change you make. For
-example:
+```bash
+@test "foobar.txt was created" {
+  run cat /usr/local/foobar.txt
+  [ "$status" -eq 0 ]
+  [ "$output" = "hello" ]
+}
+```
 
-1. Fork the repo
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+See the [Bats documentation](https://bats-core.readthedocs.io) for the full
+assertion and helper vocabulary.
 
-## Authors
+Test Kitchen picks the plugin up from the suite directory name — no verifier
+configuration is needed beyond the default busser verifier.
 
-Created and maintained by [Fletcher Nichol][author] (<fnichol@nichol.ca>)
+## Using it with Test Kitchen
 
-## License
+This is how most people run it, and it needs no Busser commands of your own.
+Select the verifier in `kitchen.yml`:
+
+```yaml
+verifier:
+  name: busser
+
+suites:
+  - name: default
+```
+
+Then put your tests in a `bats` directory inside the suite:
 
-Apache 2.0 (see [LICENSE][license])
+```text
+test/integration/default/bats/default.bats
+```
 
-[Bats][bats_site] is released under an MIT-style license, copyright Sam Stephenson.
+`kitchen verify` installs Busser and this plugin on the instance and runs them.
+The directory name is what selects this plugin -- there is nothing else to
+configure.
+
+## When nothing runs
+
+If the suite files do not match what this plugin looks for, the run prints one
+line and **exits `0`**:
+
+```text
+-----> Running bats test suite
+```
+
+No tests ran, and nothing said so. Work through these in order:
+
+1. **Is the directory named `bats`?** That name alone selects this plugin.
+   `batss/`, `tests/` or anything else is not picked up.
+2. **Do the filenames match?** Every `*.bats` file in the directory is run
+   -- `smoke.sh` is *not* picked up.
+3. **Is the plugin installed?** `busser plugin list` shows what is available.
+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
+[CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the project, run the test
+suite, and format your commits.
+
+## License
 
+Apache License 2.0. See [LICENSE](LICENSE).
 
-[author]:           https://github.com/fnichol
-[issues]:           https://github.com/fnichol/busser-bats/issues
-[license]:          https://github.com/fnichol/busser-bats/blob/master/LICENSE
-[repo]:             https://github.com/fnichol/busser-bats
+The vendored copy of Bats is released under an MIT-style license, copyright Sam
+Stephenson and the bats-core contributors.
 
-[bats_site]:  https://github.com/sstephenson/bats
+Originally created by [Fletcher Nichol](https://github.com/fnichol).

data/Rakefile

@@ -1,12 +1,17 @@
 require "bundler/gem_tasks"
-require "open-uri"
-
 namespace :bats do
-  version = ENV.fetch("BATS_VERSION", "v0.4.0")
-  url = "https://github.com/sstephenson/bats/archive/#{version}.tar.gz"
+  # bats moved. sstephenson/bats was archived in 2016 at v0.4.0; bats-core is
+  # the maintained fork and where every release since has come from.
+  version = ENV.fetch("BATS_VERSION", "v1.14.0")
+  url = "https://github.com/bats-core/bats-core/archive/refs/tags/#{version}.tar.gz"
   tarball = "tmp/bats-#{version}.tar.gz"
   vendor = "vendor/bats"
 
+  # install.sh needs bin, libexec, lib and the two man pages. Everything else in
+  # the tarball -- the test suite, the docs site, Docker and CI scaffolding --
+  # is weight in a gem that gets copied onto every machine under test.
+  keep = %w{bin libexec lib man install.sh uninstall.sh LICENSE.md README.md}
+
   desc "Vendors bats #{version} source code into gem codebase"
   task vendor: "#{vendor}/VERSION.txt"
 
@@ -14,19 +19,16 @@ namespace :bats do
   directory vendor
 
   file tarball => File.dirname(tarball) do |t|
-    src = open(url).binmode
-    dst = open(t.name, "wb")
-    IO.copy_stream(src, dst)
-  ensure
-    src.close
-    dst.close
+    sh "curl", "--fail", "--silent", "--location", url, "--output", t.name
   end
 
   file "#{vendor}/VERSION.txt" => [vendor, tarball] do |t|
     abs_tarball = File.expand_path(tarball)
-    Dir.chdir(vendor) { sh "tar xzf #{abs_tarball} --strip-components=1" }
-    rm_rf "#{vendor}/test"
-    IO.write(t.name, url + "\n")
+    Dir.chdir(vendor) do
+      sh "tar", "xzf", abs_tarball, "--strip-components=1"
+      (Dir.glob("*", File::FNM_DOTMATCH) - [".", "..", *keep]).each { |f| rm_rf(f) }
+    end
+    File.write(t.name, "#{url}\n")
   end
 
   desc "Clean up a vendored bats in preparation for a new vendored version"
@@ -35,12 +37,37 @@ namespace :bats do
   end
 end
 
+require "rake/testtask"
+Rake::TestTask.new(:unit) do |t|
+  t.libs.push "lib"
+  t.test_files = FileList["spec/**/*_spec.rb"]
+  t.verbose = true
+end
+
 require "cucumber/rake/task"
 Cucumber::Rake::Task.new(:features) do |t|
-  t.cucumber_opts = ["features", "-x", "--format progress"]
+  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"
-task test: [:features]
+task test: %i{unit features}
 
 task default: %i{test}

data/config/features/support/env.rb

@@ -1,11 +1,6 @@
 require "aruba/cucumber"
 require "busser/cucumber"
 
-if ENV["COVERAGE"]
-  require "simplecov"
-  SimpleCov.command_name "features"
-end
-
 Before do
   @aruba_timeout_seconds = 20
 end

data/features/support/env.rb

@@ -1,21 +1,9 @@
 require "aruba/cucumber"
 require "busser/cucumber"
 
-if ENV["COVERAGE"]
-  require "simplecov"
-  SimpleCov.command_name "features"
-end
-
 # aruba 2 dropped @aruba_timeout_seconds; setting it in a Before hook is a
 # no-op, which quietly left these commands on aruba's 15 second default.
 # Installing a plugin and its gems into a cold sandbox does not always fit.
 Aruba.configure do |config|
   config.exit_timeout = 60
 end
-
-After do |s|
-  # Tell Cucumber to quit after this scenario is done - if it failed.
-  # This is useful to inspect the 'tmp/aruba' directory before any other
-  # steps are executed and clear it out.
-  Cucumber.wants_to_quit = true if s.failed?
-end

data/features/test_command.feature

@@ -8,37 +8,37 @@ Feature: Test command
     When I successfully run `busser plugin install busser-bats --force-postinstall`
     Given a suite directory named "bats"
 
-#   Scenario: A passing test suite
-    # Given a file in suite "bats" named "default.bats" with:
-    # """
-    # @test "runs something" {
-    #   run echo "hello"
-    #   [ "$status" -eq 0 ]
-    #   [ "$output" == "hello" ]
-    # }
+  Scenario: A passing test suite
+    Given a file in suite "bats" named "default.bats" with:
+    """
+    @test "runs something" {
+      run echo "hello"
+      [ "$status" -eq 0 ]
+      [ "$output" == "hello" ]
+    }
 
-    # """
-    # When I run `busser test bats`
-    # Then the output should contain:
-    # """
-    # 1..1
-    # ok 1 runs something
-    # """
-    # And the exit status should be 0
+    """
+    When I run `busser test bats`
+    Then the output should contain:
+    """
+    1..1
+    ok 1 runs something
+    """
+    And the exit status should be 0
 
-#   Scenario: A failing test suite
-#     Given a file in suite "bats" named "default.bats" with:
-#     """
-#     @test "fails something" {
-#       run which uhoh-whatzit-called
-#       [ "$status" -eq 0 ]
-#     }
+  Scenario: A failing test suite
+    Given a file in suite "bats" named "default.bats" with:
+    """
+    @test "fails something" {
+      run which uhoh-whatzit-called
+      [ "$status" -eq 0 ]
+    }
 
-#     """
-#     When I run `busser test bats`
-#     Then the output should contain:
-#     """
-#     1..1
-#     not ok 1 fails something
-#     """
-#     And the exit status should not be 0
+    """
+    When I run `busser test bats`
+    Then the output should contain:
+    """
+    1..1
+    not ok 1 fails something
+    """
+    And the exit status should not be 0

data/lib/busser/bats/version.rb

@@ -16,7 +16,9 @@
 # limitations under the License.
 
 module Busser
+  # Namespace for the Bats Busser runner plugin.
   module Bats
-    VERSION = "0.6.0".freeze
+    # Version string for the Bats Busser runner plugin
+    VERSION = "0.7.0".freeze
   end
 end

data/lib/busser/runner_plugin/bats.rb

@@ -16,6 +16,7 @@
 # limitations under the License.
 
 require "pathname" unless defined?(Pathname)
+require "shellwords" unless defined?(Shellwords)
 
 require "busser/runner_plugin"
 
@@ -25,14 +26,37 @@ require "busser/runner_plugin"
 #
 class Busser::RunnerPlugin::Bats < Busser::RunnerPlugin::Base
 
+  # Installs the vendored bats onto the machine under test. Runs once, when
+  # Busser installs this plugin.
+  #
+  # bats 0.4 shipped bin/bats as a symlink that the tarball did not preserve,
+  # so this used to recreate it by hand before running install.sh. bats-core
+  # ships bin/bats as a real file, and recreating the link would replace it
+  # with one pointing at libexec/bats, which does not exist in bats-core --
+  # its executables live in libexec/bats-core.
   postinstall do
     inside(Pathname.new(__FILE__).dirname.join("../../../vendor/bats")) do
-      FileUtils.ln_sf("../libexec/bats", "bin/bats")
-      run!(%{./install.sh #{vendor_path("bats")}})
+      run!(%{./install.sh #{Shellwords.escape(vendor_path("bats").to_s)}})
     end
   end
 
+  # Builds the bats invocation.
+  #
+  # Both paths are quoted: the Busser root is user supplied through
+  # BUSSER_ROOT, and an unquoted path containing a space would be split into
+  # two arguments by the shell and silently run the wrong thing.
+  #
+  # @param bats_bin [String, Pathname] the vendored bats executable
+  # @param suite [String, Pathname] the suite directory holding the .bats files
+  # @return [String] the command to run
+  def self.command_for(bats_bin, suite)
+    %{#{Shellwords.escape(bats_bin.to_s)} #{Shellwords.escape(suite.to_s)}}
+  end
+
+  # Runs the suite's .bats files through the vendored bats.
+  #
+  # @return [void]
   def test
-    run!("#{vendor_path("bats").join("bin/bats")} #{suite_path("bats")}")
+    run!(self.class.command_for(vendor_path("bats").join("bin/bats"), suite_path("bats")))
   end
 end

data/spec/busser/runner_plugin/bats_spec.rb

@@ -0,0 +1,41 @@
+require_relative "../../spec_helper"
+
+require "shellwords"
+require "busser/runner_plugin/bats"
+
+describe Busser::RunnerPlugin::Bats do
+  describe ".command_for" do
+    it "puts the bats binary first and the suite second" do
+      cmd = Busser::RunnerPlugin::Bats.command_for("/opt/busser/vendor/bats/bin/bats",
+        "/opt/busser/suites/bats")
+
+      _(cmd).must_equal "/opt/busser/vendor/bats/bin/bats /opt/busser/suites/bats"
+    end
+
+    # BUSSER_ROOT is user supplied, and Windows-style or otherwise spaced paths
+    # do turn up. Unquoted, the shell would split the path and bats would be
+    # handed arguments nobody intended.
+    it "quotes a path containing spaces" do
+      cmd = Busser::RunnerPlugin::Bats.command_for("/opt/busser/bin/bats",
+        "/tmp/my tests/suites/bats")
+
+      # Shellwords.split is what a shell would do with this string, so this
+      # asserts the shell sees exactly two arguments rather than three.
+      _(Shellwords.split(cmd)).must_equal ["/opt/busser/bin/bats", "/tmp/my tests/suites/bats"]
+    end
+
+    it "neutralises shell metacharacters in a path" do
+      cmd = Busser::RunnerPlugin::Bats.command_for("/opt/busser/bin/bats",
+        "/tmp/a;rm -rf x/bats")
+
+      _(Shellwords.split(cmd)).must_equal ["/opt/busser/bin/bats", "/tmp/a;rm -rf x/bats"]
+    end
+
+    it "accepts Pathname arguments" do
+      cmd = Busser::RunnerPlugin::Bats.command_for(Pathname.new("/a/bats"),
+        Pathname.new("/b/suites/bats"))
+
+      _(cmd).must_equal "/a/bats /b/suites/bats"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require "minitest/autorun"
+require "mocha/minitest"