kitchen-docker 3.2.4 → 3.3.1

data/spec/support/argv.rb

@@ -0,0 +1,55 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "shellwords"
+
+# Helpers for asserting on generated command lines.
+#
+# The driver builds `docker` invocations as single strings and hands them to a
+# shell. Asserting on those strings with `include` is misleading: the string
+# "-v /my volume:/data" contains "-v /my volume:/data", but the shell will tear
+# it into three arguments and Docker will reject it. Splitting the command the
+# way a shell would, and asserting on the resulting argument vector, is the only
+# way for a test to see what Docker will actually receive.
+module ArgvHelpers
+  # Splits a generated command line the way a shell would.
+  #
+  # @param command [String] the command line the driver built
+  # @return [Array<String>] the arguments Docker will actually receive
+  def argv(command)
+    Shellwords.split(command)
+  end
+end
+
+# Asserts that a flag and its value survive shell splitting as one argument
+# each, and remain adjacent.
+#
+# `include` alone cannot express this: an argv of ["-v", "/my", "volume:/data"]
+# includes "-v", and includes "/my", and would satisfy a naive assertion while
+# being completely broken.
+RSpec::Matchers.define :include_consecutive do |*expected|
+  match do |actual|
+    actual.each_cons(expected.length).any? { |window| window == expected }
+  end
+
+  failure_message do |actual|
+    "expected the argument vector to contain #{expected.inspect} as consecutive arguments\n" \
+      "                                 got: #{actual.inspect}"
+  end
+
+  failure_message_when_negated do |actual|
+    "expected the argument vector not to contain #{expected.inspect} as consecutive arguments\n" \
+      "                                     got: #{actual.inspect}"
+  end
+end

data/spec/support/docker_output.rb

@@ -0,0 +1,117 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Output captured from real `docker` invocations.
+#
+# The driver's parsers are the part of this gem most exposed to change outside
+# it: Docker has rewritten its build output at least three times, and each
+# rewrite has broken image-id parsing. Inventing plausible-looking output tests
+# nothing, because a parser written against an invented format will happily
+# agree with it. These strings are copied from actual runs, and the version that
+# produced each one is recorded, so the suite says what it is compatible with.
+module DockerOutput
+  # `docker build` on Docker 29.7.2 with BuildKit and BUILDKIT_PROGRESS=plain,
+  # which is how ImageHelper#build_image invokes it.
+  #
+  # Note there is no "writing image" line: BuildKit stopped emitting one, and
+  # the id now appears only in the "naming to moby-dangling@" line.
+  BUILD_29_7_BUILDKIT = <<~OUTPUT.freeze
+    #1 [internal] load build definition from Dockerfile-kitchen
+    #1 transferring dockerfile: 92B done
+    #1 DONE 0.0s
+
+    #2 [internal] load metadata for docker.io/library/alpine:3.20
+    #2 DONE 0.0s
+
+    #5 [1/2] FROM docker.io/library/alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc
+    #5 resolve docker.io/library/alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc done
+    #5 DONE 0.3s
+
+    #6 [2/2] RUN echo hello
+    #6 0.085 hello
+    #6 DONE 0.1s
+
+    #6 exporting to image
+    #6 exporting layers 0.0s done
+    #6 exporting manifest sha256:11bf8269eec601a760f884a563cf714dd02eacc5f1e6cd598cc49c3a031dab0f done
+    #6 exporting config sha256:30ca0fb0b01c490a57ae08f426919a7ca3f69737085b28d47847427dbce4e7c2 done
+    #6 exporting attestation manifest sha256:530b259bbff0d8c05488739e6fff58a482596104bd8ca6bdb640f1687fe7e6bf done
+    #6 exporting manifest list sha256:aba3aa20a98ea7578c1b41b4e5b17c71e64d1b7eccd5a4242d3f3956c327d8d4 done
+    #6 naming to moby-dangling@sha256:aba3aa20a98ea7578c1b41b4e5b17c71e64d1b7eccd5a4242d3f3956c327d8d4 done
+    #6 unpacking to moby-dangling@sha256:aba3aa20a98ea7578c1b41b4e5b17c71e64d1b7eccd5a4242d3f3956c327d8d4 done
+    #6 DONE 0.0s
+  OUTPUT
+
+  # The image id in BUILD_29_7_BUILDKIT. Verified runnable: `docker run` accepts
+  # it, so this really is the id the driver should carry into `state[:image_id]`.
+  BUILD_29_7_IMAGE_ID = "sha256:aba3aa20a98ea7578c1b41b4e5b17c71e64d1b7eccd5a4242d3f3956c327d8d4".freeze
+
+  # BuildKit as it emitted the id before the "naming to moby-dangling" form.
+  BUILD_BUILDKIT_WRITING_IMAGE = <<~OUTPUT.freeze
+    #8 exporting to image
+    #8 exporting layers 0.4s done
+    #8 writing image sha256:9d3a1b2c4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9 0.0s done
+    #8 naming to docker.io/library/kitchen-docker done
+    #8 DONE 0.5s
+  OUTPUT
+
+  BUILD_BUILDKIT_WRITING_IMAGE_ID =
+    "sha256:9d3a1b2c4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9".freeze
+
+  # The pre-BuildKit builder, still reachable with DOCKER_BUILDKIT=0.
+  BUILD_LEGACY = <<~OUTPUT.freeze
+    Step 3/3 : RUN echo hello
+     ---> Running in 4f2c1a9b8e7d
+    hello
+    Removing intermediate container 4f2c1a9b8e7d
+     ---> 1a2b3c4d5e6f
+    Successfully built 1a2b3c4d5e6f
+  OUTPUT
+
+  BUILD_LEGACY_IMAGE_ID = "1a2b3c4d5e6f".freeze
+
+  # `docker run -d`, the ordinary case: the id and nothing else.
+  RUN_CONTAINER_ID = "b89e1e8b07664a1ee0bd09decb833146eaf9cc810a152950e3576a56745944db".freeze
+  RUN_CLEAN = "#{RUN_CONTAINER_ID}\n".freeze
+
+  # `docker run -d` when the image is not cached locally. Every line after the
+  # id went to stderr, and CliHelper#run_command returns stdout + stderr, so
+  # this whole string is what the container-id parser is handed.
+  #
+  # Captured from Docker 29.7.2.
+  RUN_WITH_PULL_ON_STDERR = <<~OUTPUT.freeze
+    #{RUN_CONTAINER_ID}
+    Unable to find image 'alpine:3.20' locally
+    3.20: Pulling from library/alpine
+    25f1d6b1951a: Pulling fs layer
+    25f1d6b1951a: Pull complete
+    Digest: sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc
+    Status: Downloaded newer image for alpine:3.20
+  OUTPUT
+
+  # The warning Docker emits on `run` on hosts whose kernel lacks swap
+  # accounting -- the default on Ubuntu. It goes to stderr, so it too is
+  # concatenated onto the container id.
+  RUN_WITH_SWAP_WARNING = "#{RUN_CONTAINER_ID}\nWARNING: No swap limit support\n".freeze
+
+  # `docker port <container> 22/tcp` on a dual-stack daemon. Docker 29.7.2.
+  PORT_DUAL_STACK = "0.0.0.0:52239\n[::]:52239\n".freeze
+
+  # The same, on a daemon publishing only on IPv6.
+  PORT_IPV6_ONLY = "[::]:52239\n".freeze
+
+  PORT_IPV4_ONLY = "0.0.0.0:52239\n".freeze
+
+  PUBLISHED_PORT = 52_239
+end

data/spec/support/harness.rb

@@ -0,0 +1,70 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Builds throwaway objects that mix in the driver's helper modules.
+#
+# The helpers are modules meant to be mixed into the driver, the transport, and
+# the container classes. Testing them through one of those means dragging in a
+# Test Kitchen instance, a platform, and a logger to exercise what is really
+# just string building -- so mix them into a bare object with a config hash
+# instead, which is what they actually depend on.
+module HelperHarness
+  # Every helper module, which is what the driver itself mixes in.
+  ALL_HELPERS = [
+    Kitchen::Docker::Helpers::CliHelper,
+    Kitchen::Docker::Helpers::ContainerHelper,
+    Kitchen::Docker::Helpers::DockerfileHelper,
+    Kitchen::Docker::Helpers::ImageHelper,
+    Kitchen::Docker::Helpers::FileHelper,
+  ].freeze
+
+  # Takes its configuration positionally rather than as keywords, so that
+  # `helper(build_context: true)` cannot be mistaken for a keyword argument.
+  #
+  # @param config [Hash] driver configuration the helpers will read
+  # @return [Object] an object responding to every helper method
+  def helper(config = {})
+    klass = Class.new do
+      attr_accessor :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      # Methods defined in the class body win over included modules regardless
+      # of include order, so these override anything the helpers bring in.
+      def logger
+        Kitchen.logger
+      end
+
+      # Kitchen::Logging's levels, silenced -- the helpers log freely and the
+      # output is noise in a test run.
+      %i{debug info warn error fatal}.each do |level|
+        define_method(level) { |*| nil }
+      end
+    end
+
+    ALL_HELPERS.each { |mod| klass.include(mod) }
+    klass.new(default_config.merge(config))
+  end
+
+  # Config the helpers read on nearly every path. Individual examples override
+  # what they care about, so each example states only what it is testing.
+  def default_config
+    {
+      binary: "docker",
+      socket: "unix:///var/run/docker.sock",
+    }
+  end
+end

data/spec/transport_docker_spec.rb

@@ -0,0 +1,130 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "spec_helper"
+require "kitchen/transport/docker"
+
+describe Kitchen::Transport::Docker::Connection do
+  let(:options) do
+    {
+      binary: "docker",
+      container_id: "abc123",
+      platform: "ubuntu-24.04",
+      socket: "unix:///var/run/docker.sock",
+      username: "kitchen",
+    }
+  end
+
+  subject(:connection) { described_class.new(options) }
+
+  # The class is declared inside `class Docker < Kitchen::Transport::Base`, so
+  # its superclass is reached through Ruby's ancestor constant lookup rather
+  # than being spelled out. Pin it, so the inheritance cannot drift.
+  it "inherits from the Test Kitchen base connection" do
+    expect(described_class.superclass).to be Kitchen::Transport::Base::Connection
+  end
+
+  describe "#login_command" do
+    subject(:login_command) { connection.login_command }
+
+    it "returns a Kitchen::LoginCommand" do
+      expect(login_command).to be_a(Kitchen::LoginCommand)
+    end
+
+    it "execs the docker binary" do
+      expect(login_command.command).to eq "docker"
+    end
+
+    it "opens an interactive login shell on a Linux container" do
+      expect(login_command.arguments).to eq %w{
+        -H unix:///var/run/docker.sock
+        exec -t -i -u kitchen abc123 /bin/bash --login -i
+      }
+    end
+
+    it "passes each flag and its value as separate argv tokens" do
+      expect(login_command.arguments).to include("-H", "unix:///var/run/docker.sock")
+      expect(login_command.arguments).not_to include("-H unix:///var/run/docker.sock")
+    end
+
+    context "on a Windows container" do
+      let(:options) do
+        {
+          binary: "docker",
+          container_id: "abc123",
+          platform: "windows-2022",
+          socket: "tcp://localhost:2375",
+          username: nil,
+        }
+      end
+
+      it "opens a PowerShell session instead of bash" do
+        expect(login_command.arguments).to eq %w{
+          -H tcp://localhost:2375
+          exec -t -i abc123 powershell
+        }
+      end
+    end
+
+    context "with TLS configured" do
+      before do
+        options.merge!(
+          tls: true,
+          tls_verify: true,
+          tls_cacert: "/certs/ca.pem",
+          tls_cert: "/certs/cert.pem",
+          tls_key: "/certs/key.pem"
+        )
+      end
+
+      it "includes the TLS flags before the exec subcommand" do
+        expect(login_command.arguments.take(8)).to eq %w{
+          -H unix:///var/run/docker.sock
+          --tls --tlsverify
+          --tlscacert=/certs/ca.pem
+          --tlscert=/certs/cert.pem
+          --tlskey=/certs/key.pem
+          exec
+        }
+      end
+    end
+
+    context "with a working directory and environment variables" do
+      before do
+        options.merge!(working_dir: "/opt/kitchen", env_variables: { FOO: "bar" })
+      end
+
+      it "passes them through to docker exec" do
+        expect(login_command.arguments).to include("-w", "/opt/kitchen")
+        expect(login_command.arguments).to include("-e", "FOO=bar")
+      end
+    end
+
+    context "when the transport is configured to detach" do
+      before { options.merge!(detach: true) }
+
+      it "still runs attached so the session is usable" do
+        expect(login_command.arguments).not_to include("-d")
+      end
+    end
+
+    context "when the transport is configured as privileged" do
+      before { options.merge!(privileged: true) }
+
+      it "keeps the privileged flag" do
+        expect(login_command.arguments).to include("--privileged")
+      end
+    end
+  end
+end

data/spec/windows_container_spec.rb

@@ -0,0 +1,101 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "spec_helper"
+require "tmpdir"
+
+describe Kitchen::Docker::Container::Windows do
+  def container(config = {})
+    described_class.new({
+      image: "mcr.microsoft.com/windows/servercore:ltsc2022",
+      platform: "windows",
+      username: "administrator",
+    }.merge(config))
+  end
+
+  describe "#dockerfile" do
+    subject(:dockerfile) { container.send(:dockerfile) }
+
+    it "starts from the configured image" do
+      expect(dockerfile.lines.first.strip).to eq "FROM mcr.microsoft.com/windows/servercore:ltsc2022"
+    end
+
+    it "installs no SSH server" do
+      # Windows containers are driven entirely through `docker exec`. Emitting
+      # the Linux SSH setup here would fail the build on the first RUN.
+      expect(dockerfile).not_to match(/openssh|authorized_keys|sshd/)
+    end
+
+    it "appends each provision_command as its own RUN line" do
+      expect(container(provision_command: ["powershell -Command a", "powershell -Command b"]).send(:dockerfile))
+        .to include("RUN powershell -Command a\n").and include("RUN powershell -Command b\n")
+    end
+
+    it "carries the proxy configuration into the image" do
+      expect(container(http_proxy: "http://proxy:8080").send(:dockerfile))
+        .to include "ENV http_proxy=http://proxy:8080"
+    end
+
+    it "refuses to build for a non-Windows platform" do
+      # Reaching here with platform: ubuntu means the driver picked the wrong
+      # container class, and the resulting image would be silently wrong.
+      expect { container(platform: "ubuntu").send(:dockerfile) }
+        .to raise_error(Kitchen::ActionFailed, /Unknown platform 'ubuntu'/)
+    end
+
+    it "uses a custom dockerfile verbatim when configured" do
+      Dir.mktmpdir do |dir|
+        path = File.join(dir, "Dockerfile")
+        File.write(path, "FROM <%= @image %>\n")
+        expect(container(dockerfile: path).send(:dockerfile))
+          .to eq "FROM mcr.microsoft.com/windows/servercore:ltsc2022\n"
+      end
+    end
+  end
+
+  describe "the contract it shares with the Linux container" do
+    # The two classes share almost no code but must agree on the state they
+    # populate, because the driver and transport read the same keys whichever
+    # one ran. A key added on one side and forgotten on the other shows up as a
+    # nil far away from the cause.
+    it "publishes no port, because there is no SSH server to reach" do
+      c = container
+      allow(c).to receive(:build_image).and_return("sha256:abc")
+      allow(c).to receive(:container_exists?).and_return(false)
+      allow(c).to receive(:hostname).and_return("localhost")
+      expect(c).to receive(:run_container).with(anything).and_return("abc123")
+
+      state = {}
+      c.create(state)
+      expect(state).not_to have_key(:port)
+    end
+
+    it "records the container id, image id, hostname, and username" do
+      c = container
+      allow(c).to receive(:build_image).and_return("sha256:abc")
+      allow(c).to receive(:container_exists?).and_return(false)
+      allow(c).to receive(:run_container).and_return("abc123")
+      allow(c).to receive(:hostname).and_return("localhost")
+
+      state = {}
+      c.create(state)
+      expect(state).to include(
+        image_id: "sha256:abc",
+        container_id: "abc123",
+        hostname: "localhost",
+        username: "administrator"
+      )
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-docker
 version: !ruby/object:Gem::Version
-  version: 3.2.4
+  version: 3.3.1
 platform: ruby
 authors:
 - Sean Porter
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-kitchen
@@ -45,7 +45,9 @@ files:
 - ".release-please-manifest.json"
 - ".rubocop.yml"
 - ".yamllint"
+- ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE
 - README.md
@@ -70,24 +72,31 @@ files:
 - lib/kitchen/transport/docker.rb
 - release-please-config.json
 - renovate.json
+- spec/cli_helper_spec.rb
+- spec/container_helper_spec.rb
 - spec/docker_spec.rb
 - spec/dockerfile_helper_spec.rb
+- spec/erb_context_spec.rb
+- spec/image_helper_spec.rb
 - spec/inspec_helper_spec.rb
+- spec/linux_container_spec.rb
 - spec/spec_helper.rb
+- spec/support/argv.rb
+- spec/support/docker_output.rb
+- spec/support/harness.rb
+- spec/transport_docker_spec.rb
+- spec/windows_container_spec.rb
 - test/Dockerfile
 - test/cookbooks/cinc_test/metadata.rb
 - test/cookbooks/cinc_test/recipes/default.rb
 - test/cookbooks/docker_test/attributes/default.rb
 - test/cookbooks/docker_test/metadata.rb
 - test/cookbooks/docker_test/recipes/default.rb
-- test/integration/capabilities/disabled/capabilities_drop_spec.rb
 - test/integration/cinc/inspec/cinc_spec.rb
-- test/integration/default/disabled/default_spec.rb
-- test/integration/default/disabled/spec_helper.rb
 - test/integration/inspec/inspec_spec.rb
 homepage: https://github.com/test-kitchen/kitchen-docker
 licenses:
-- Apache 2.0
+- Apache-2.0
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -97,7 +106,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/test/integration/capabilities/disabled/capabilities_drop_spec.rb

@@ -1,24 +0,0 @@
-#
-# Copyright 2016, Noah Kantrowitz
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-
-# Disable now busser-serever is gone.
-# require 'serverspec'
-# set :backend, :exec
-
-# describe command('/sbin/ifconfig eth0 multicast') do
-#   its(:exit_status) { is_expected.to_not eq 0 }
-#   its(:stderr) { is_expected.to match /Operation not permitted/ }
-# end

data/test/integration/default/disabled/default_spec.rb

@@ -1,24 +0,0 @@
-#
-# Copyright 2016, Noah Kantrowitz
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-
-# Disable now busser-server is gone.
-# require "serverspec"
-# require "spec_helper"
-#
-# Just make sure the image launched and is reachable.
-# describe command("true") do
-#   its(:exit_status) { is_expected.to eq 0 }
-# end

data/test/integration/default/disabled/spec_helper.rb

@@ -1,21 +0,0 @@
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-
-# case RbConfig::CONFIG['host_os']
-# when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-#   set :backend, :cmd
-#   set :os, :family => 'windows'
-# else
-#   set :backend, :exec
-# end