kitchen-docker 3.3.4 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be40fecdd59251c4d7b1a20de831bd939fd7018ce19d19a2a2f205ac2464f4fb
-  data.tar.gz: 04b4579a2569e8be9f943d77eca1d4fd9f5e72e2aefc2ad3009855bf1e565935
+  metadata.gz: 7cacd3efc6d10490456e00f5d077a3a1eb8f96bb5aef71c6c93b8d2044823a1f
+  data.tar.gz: f6c3337ecdc3da7c134da8506472e7237b85a9784dd63fb5b46fa996303539b6
 SHA512:
-  metadata.gz: d14d1fcddd8c823cc51231351311d2130bb9e9dd8355bb09e0551635a982a38b8abc52fca32cb03b5813d484bc256a688574ad8da6ef44a3d20525bdeac8fb21
-  data.tar.gz: 93f7faf2b089f727c6c78808b6c3e4d3fc9234e22a4defa21a0b463b61992324d8ecd26fb5bb9bfbc7da415d00234c67815d7bc20e889c563da50324c76c1040
+  metadata.gz: ec737baa038bf371481c82599263ed09cf98921f687da8cb45e52f1becd13d75417fb545d72338806c533dee99d4b1a39d4c47618e8c15709487937557c30c75
+  data.tar.gz: e8434376fb8dd607f224de53137d18ee4f9c644c1205b7341cbe3bcc43c7c07ad2aa575fb0ba5cdc7350ee721d6b0fcf6cb781f73421b2251cbfede68f154a0d

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.3.4"
+  ".": "3.4.0"
 }

data/CHANGELOG.md

@@ -6,6 +6,23 @@ Future CHANGELOG notes will be in GitHub release notes
 
 * Docs: document the last four options and split contributor docs ([#463](https://github.com/test-kitchen/kitchen-docker/pull/463)) ([4818bce](https://github.com/test-kitchen/kitchen-docker/commit/4818bce))
 
+## [3.4.0](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.5...v3.4.0) (2026-08-23)
+
+
+### Features
+
+* implement the driver's package, doctor, and status hooks ([#491](https://github.com/test-kitchen/kitchen-docker/issues/491)) ([1366895](https://github.com/test-kitchen/kitchen-docker/commit/13668957b5b802f91c30aa7e34fc1b9f761e3b8d))
+
+## [3.3.5](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.4...v3.3.5) (2026-08-23)
+
+
+### Bug Fixes
+
+* report when docker cp silently writes nothing ([#487](https://github.com/test-kitchen/kitchen-docker/issues/487)) ([1bc62ba](https://github.com/test-kitchen/kitchen-docker/commit/1bc62ba615d25d402a97775dbf6ac252af5cbdd8))
+* require test-kitchen 3.0 or newer ([#492](https://github.com/test-kitchen/kitchen-docker/issues/492)) ([0c64225](https://github.com/test-kitchen/kitchen-docker/commit/0c64225dd22aca8a2a32e6f61a6d648bcd8c0b2b))
+* run every docker command through sudo when use_sudo is set ([#485](https://github.com/test-kitchen/kitchen-docker/issues/485)) ([2481aad](https://github.com/test-kitchen/kitchen-docker/commit/2481aadfc6415e5b7ed597e1095d0fe8db89afbb))
+* stop printing the image inspect JSON on destroy ([#488](https://github.com/test-kitchen/kitchen-docker/issues/488)) ([0011558](https://github.com/test-kitchen/kitchen-docker/commit/00115588236900d9ef3275a73892f9d3bdb4e3c8))
+
 ## [3.3.4](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.3...v3.3.4) (2026-08-23)
 
 

data/README.md

@@ -28,6 +28,7 @@ machine to boot.
 * [Driver configuration](#driver-configuration)
 * [Transport configuration](#transport-configuration)
 * [Logging into a container](#logging-into-a-container)
+* [Other commands](#other-commands)
 * [Examples](#examples)
 * [Using with Chef](#using-with-chef)
 * [Troubleshooting](#troubleshooting)
@@ -207,6 +208,7 @@ platforms:
 | `build_tempdir` | working directory | Where the generated Dockerfile is written, relative to `build_context`. |
 | `use_cache` | `true` | Use Docker's build cache. `false` adds `--no-cache`. |
 | `remove_images` | `false` | Remove the built image on `kitchen destroy`. |
+| `package_name` | the instance name, tagged `latest` | Image `kitchen package` commits the container to. |
 | `docker_platform` | *(none)* | Target architecture, passed as `--platform` to both build and run — e.g. `linux/arm64`. |
 
 ### Provisioning the image
@@ -284,6 +286,7 @@ Each of these accepts a single value or a list.
 | `binary` | `docker` | Docker CLI to invoke — e.g. `docker.io`, or an absolute path. |
 | `socket` | `$DOCKER_HOST`, else `unix:///var/run/docker.sock` (`npipe:////./pipe/docker_engine` on Windows) | Daemon to talk to. A `tcp://` value also supplies the host used for SSH to the container. |
 | `use_sudo` | `false` | Run every `docker` command through `sudo`. |
+| `sudo_command` | `sudo -E` | The command `use_sudo` prefixes, for hosts that use something else (`doas`, say). |
 | `tls` | `false` | Use TLS when connecting. |
 | `tls_verify` | `false` | Verify the daemon's certificate. |
 | `tls_cacert` | *(none)* | Path to the CA certificate. |
@@ -314,11 +317,13 @@ These options go under `transport:`, not `driver:`.
 | `privileged` | `false` | Run commands with `--privileged`. |
 | `interactive` | `false` | Pass `-i`. |
 | `tty` | `false` | Pass `-t`. |
+| `use_sudo` | `false` | Run every `docker` command through `sudo`. |
+| `sudo_command` | `sudo -E` | The command `use_sudo` prefixes. |
 | `tls`, `tls_verify`, `tls_cacert`, `tls_cert`, `tls_key` | as for the driver | TLS settings for the daemon connection. |
 
 The driver and transport each read their own copy of `binary`, `socket`,
-`username`, and the TLS settings. If you point one at a non-default daemon,
-point the other at it too.
+`username`, `use_sudo`, and the TLS settings. If you point one at a non-default
+daemon, or need `sudo` to reach it, configure the other the same way.
 
 ## Logging into a container
 
@@ -334,6 +339,68 @@ starts `powershell`. The transport's `username`, `working_dir`,
 `env_variables`, and `privileged` settings are honoured, so the shell matches
 the environment the provisioner ran in.
 
+## Other commands
+
+### `kitchen package`
+
+Commits the container to a Docker image, so a converged instance can be kept
+and reused:
+
+```sh
+kitchen package default-ubuntu-2404
+```
+
+```text
+-----> Packaging remote instance
+       [Docker] Packaged default-ubuntu-2404 as default-ubuntu-2404:latest (sha256:1f51c590...)
+```
+
+The image is named after the instance. Set `package_name` for something else:
+
+```yaml
+driver:
+  name: docker
+  package_name: myapp/under-test:candidate
+```
+
+Run `docker save` against the result if you want a tarball.
+
+### `kitchen doctor`
+
+Checks that the daemon is reachable and that the configuration points at
+things that exist:
+
+```sh
+kitchen doctor default-ubuntu-2404
+```
+
+```text
+-----> The doctor is in
+       Docker daemon at unix:///var/run/docker.sock is reachable, running 29.7.2.
+```
+
+It reports every problem it finds rather than stopping at the first, and exits
+non-zero when there is one: a daemon it cannot reach, a `tls_cacert`,
+`tls_cert`, `tls_key`, or `dockerfile` naming a path that is not there, or a
+state file naming a container the daemon no longer has.
+
+### `kitchen list --live`
+
+Asks Docker what state each container is actually in, rather than reporting
+only the last action Test Kitchen took:
+
+```sh
+kitchen list --live
+```
+
+```text
+Instance             Driver  Provisioner  Verifier  Transport  Last Action  Last Error  Live Status
+default-ubuntu-2404  Docker  Shell        Dummy     Docker     Created      <None>      running
+```
+
+`running`, `stopped`, `gone` (the state file names a container the daemon does
+not have), or `not created`.
+
 ## Examples
 
 ### Testing a systemd service
@@ -534,7 +601,8 @@ bootstrap. Set it to a supported family, or supply your own
 to `false` against a remote daemon.
 
 **Permission denied talking to the daemon.** Either add your user to the
-`docker` group, or set `use_sudo: true`.
+`docker` group, or set `use_sudo: true` under **both** `driver:` and
+`transport:` -- the transport runs its own `docker exec` and `docker cp`.
 
 **Anything else.** Run with `-l debug`:
 

data/kitchen-docker.gemspec

@@ -16,5 +16,5 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split($/)
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "test-kitchen", ">= 1.0.0", "< 5.0"
+  spec.add_dependency "test-kitchen", ">= 3.0", "< 5.0"
 end

data/lib/kitchen/docker/docker_version.rb

@@ -18,6 +18,6 @@ module Kitchen
   # Everything belonging to the kitchen-docker plugin.
   module Docker
     # The version of the kitchen-docker gem.
-    DOCKER_VERSION = "3.3.4".freeze
+    DOCKER_VERSION = "3.4.0".freeze
   end
 end

data/lib/kitchen/docker/helpers/cli_helper.rb

@@ -64,11 +64,39 @@ module Kitchen
           docker << " --tlscacert=#{shell_escape(config[:tls_cacert])}" if config[:tls_cacert]
           docker << " --tlscert=#{shell_escape(config[:tls_cert])}" if config[:tls_cert]
           docker << " --tlskey=#{shell_escape(config[:tls_key])}" if config[:tls_key]
+          options = docker_sudo_opts(options)
           logger.debug("docker_command: #{docker} #{cmd} shell_opts: #{docker_shell_opts(options)}")
           run_command("#{docker} #{cmd}", docker_shell_opts(options))
         end
         # rubocop:enable Metrics/AbcSize
 
+        # Adds the sudo options {#run_command} reads, when +use_sudo+ is set.
+        #
+        # Sudo is a property of the call rather than of the configuration as far
+        # as the shell-out layer is concerned: it reads +:use_sudo+ from the
+        # options hash it is handed and knows nothing about +config+. So a
+        # docker command only runs through sudo if these are passed to it.
+        #
+        # Without this, +use_sudo+ reached exactly one command -- the
+        # `docker` probe in +verify_dependencies+ -- and every build, run,
+        # exec, cp, and rm still ran as the invoking user. On a host where the
+        # daemon socket needs root, that made the documented answer to
+        # "permission denied while trying to connect to the Docker daemon
+        # socket" do nothing at all.
+        #
+        # A copy is returned rather than the hash being edited in place, so a
+        # caller that reuses its options hash does not accumulate sudo.
+        #
+        # @param options [Hash] shell-out options
+        # @return [Hash] those options, with sudo added when configured
+        def docker_sudo_opts(options = {})
+          return options unless config[:use_sudo]
+
+          options = options.merge(use_sudo: true)
+          options[:sudo_command] = config[:sudo_command] if config[:sudo_command]
+          options
+        end
+
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
 
         # Runs a shell command, returning stderr as well as stdout.

data/lib/kitchen/docker/helpers/container_helper.rb

@@ -33,6 +33,11 @@ module Kitchen
         include Configurable
         include Kitchen::Docker::Helpers::CliHelper
 
+        # Printed by the probe in {#file_on_container?} when the file is there.
+        # A marker is echoed rather than the exit status being read, because a
+        # non-zero exit from `docker exec` is raised rather than returned.
+        COPIED_MARKER = "kitchen_docker_copied".freeze
+
         # Pulls the container id out of `docker run` output.
         #
         # Docker prints ids in short (12) or full (64) hex form, on a line of
@@ -172,23 +177,84 @@ module Kitchen
 
         # Copies a local file into the container.
         #
+        # The copy is checked afterwards, because `docker cp` cannot write into
+        # a mount and does not say so. A destination under a tmpfs or a volume
+        # is written to the container's own filesystem layer, which the mount
+        # then hides, and docker exits 0 with no output -- so the copy looks
+        # like it worked and the file is simply not there.
+        #
+        # Left unchecked, that surfaces later and somewhere else. Running with
+        # `tmpfs: /tmp`, which is how the Docker documentation suggests running
+        # systemd, the first sign is the next command failing with
+        # `/bin/bash: /tmp/docker-<uuid>.sh: No such file or directory` (#387),
+        # which names neither the copy nor the mount.
+        #
         # @param state [Hash] instance state naming the container
         # @param local_file [String] source path
         # @param remote_file [String] destination path inside the container
         # @return [String] the command's combined output
-        # @raise [RuntimeError] if the copy fails
+        # @raise [RuntimeError] if the copy fails, or if it silently wrote
+        #   nothing
         def copy_file_to_container(state, local_file, remote_file)
           debug("Copying local file #{local_file} to #{remote_file} on container")
 
           remote_file = replace_env_variables(state, remote_file)
 
-          remote_file = "#{state[:container_id]}:#{remote_file}"
-          cmd = build_copy_command(local_file, remote_file)
-          docker_command(cmd)
+          cmd = build_copy_command(local_file, "#{state[:container_id]}:#{remote_file}")
+          output = docker_command(cmd)
+          verify_file_copied(state, local_file, remote_file)
+          output
         rescue => e
           raise "Failed to copy file #{local_file} to container. #{e}"
         end
 
+        # Checks that a copied file arrived, and says why if it did not.
+        #
+        # Only Linux containers are checked. tmpfs mounts are a Linux container
+        # feature, and `docker cp` against a Windows container is a different
+        # code path in Docker that this cannot be tried against, so those keep
+        # the behaviour they have always had.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param local_file [String] the source that was copied
+        # @param remote_file [String] the destination it was copied to
+        # @return [void]
+        # @raise [Kitchen::ActionFailed] if the file is not there
+        def verify_file_copied(state, local_file, remote_file)
+          return if state[:platform].to_s.include?("windows")
+          return if file_on_container?(state, remote_file, ::File.basename(local_file))
+
+          raise ActionFailed,
+            "docker reported no error copying it to #{remote_file}, but the file is " \
+            "not there. `docker cp` cannot write into a mount -- if #{remote_file} is " \
+            "a tmpfs or a volume, set the transport's temp_dir and the provisioner's " \
+            "root_path to a path that is not."
+        end
+
+        # Whether a `docker cp` destination now holds the file that was copied.
+        #
+        # `docker cp SRC CONTAINER:DEST` copies into DEST when DEST is a
+        # directory and to DEST otherwise. Which of those happened is only known
+        # inside the container, so the choice is made there, in the one command,
+        # rather than by asking twice from here.
+        #
+        # The two paths are passed as arguments to `sh` rather than interpolated
+        # into the script, so that nothing in either is read as shell syntax.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param remote_file [String] the destination that was copied to
+        # @param basename [String] the source's file name
+        # @return [Boolean] whether the file is there
+        def file_on_container?(state, remote_file, basename)
+          script = 'p="$1"; if [ -d "$p" ]; then p="$p/$2"; fi; ' \
+                   "if [ -e \"$p\" ]; then echo #{COPIED_MARKER}; fi"
+          probe = "/bin/sh -c #{Shellwords.escape(script)} sh " \
+                  "#{Shellwords.escape(remote_file)} #{Shellwords.escape(basename)}"
+
+          output = docker_command(build_exec_command(state, probe), suppress_output: !logger.debug?)
+          output.include?(COPIED_MARKER)
+        end
+
         # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
 
         # Reads the container's environment.

data/lib/kitchen/docker/helpers/image_helper.rb

@@ -126,10 +126,28 @@ module Kitchen
           parse_image_id(output)
         end
 
+        # Whether the image named in state is present locally.
+        #
+        # The inspect is silenced, as every other predicate that shells out to
+        # docker is. Left speaking, `kitchen destroy` on an instance with
+        # +remove_images+ set printed the image's entire `docker inspect` JSON
+        # -- config, every layer digest, metadata -- into the middle of the
+        # destroy output, between the container being removed and the image
+        # being removed. Nothing read it: only whether the command succeeded is
+        # used.
+        #
+        # It is still printed under `-l debug`, where the rest of the driver's
+        # docker traffic is.
+        #
         # @param state [Hash] instance state naming the image
         # @return [Boolean] whether the image is present locally
         def image_exists?(state)
-          state[:image_id] && !!docker_command("inspect --type=image #{state[:image_id]}") rescue false
+          return false unless state[:image_id]
+
+          !!docker_command("inspect --type=image #{state[:image_id]}",
+            suppress_output: !logger.debug?)
+        rescue
+          false
         end
       end
     end

data/lib/kitchen/driver/docker.rb

@@ -17,6 +17,7 @@ require "kitchen"
 require "json" unless defined?(JSON)
 require "securerandom" unless defined?(SecureRandom)
 require "net/ssh" unless defined?(Net::SSH)
+require "time" unless defined?(Time)
 
 require "kitchen/driver/base"
 
@@ -52,6 +53,7 @@ module Kitchen
       default_config :remove_images, false
       default_config :run_options,   nil
       default_config :security_opt,  nil
+      default_config :sudo_command,  nil
       default_config :tls,           false
       default_config :tls_cacert,    nil
       default_config :tls_cert,      nil
@@ -79,6 +81,13 @@ module Kitchen
         ].join("-").downcase
       end
 
+      # The image `kitchen package` commits to. Derived from the instance name,
+      # which is already lowercase and dash-separated, so it is a valid Docker
+      # repository name as it stands.
+      default_config :package_name do |driver|
+        "#{driver.instance.name.downcase.gsub(/[^a-z0-9_.-]/, "-")}:latest"
+      end
+
       default_config :platform, &:default_platform
 
       default_config :run_command do |driver|
@@ -140,6 +149,82 @@ module Kitchen
         container.destroy(state)
       end
 
+      # Commits the container to a Docker image.
+      #
+      # `kitchen package` asks a driver to turn a converged instance into
+      # something reusable. For Docker that is an image: `docker commit` on the
+      # running container, which is the artifact every other docker tool
+      # already takes. Run `docker save` against the result for a tarball.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if the instance has not been created
+      def package(state)
+        unless state[:container_id]
+          raise ActionFailed, "Cannot package #{instance.name}: it has not been created."
+        end
+
+        # Asked here rather than left to `docker commit`, which reports a
+        # container that is gone as a bare "Error response from daemon: No such
+        # container: <64 hex characters>" with nothing about the instance or
+        # what to do next.
+        unless container_exists?(state)
+          raise ActionFailed, "Cannot package #{instance.name}: the state file names container " \
+                              "#{state[:container_id]}, which the daemon does not have. " \
+                              "Run `kitchen destroy` to clear it."
+        end
+
+        name = config[:package_name]
+        info("[Docker] Committing container #{state[:container_id]} to #{name}")
+        output = docker_command("commit #{shell_escape(state[:container_id])} #{shell_escape(name)}",
+          suppress_output: !logger.debug?)
+        image_id = output.lines.map(&:strip).find { |line| line.match?(/\Asha256:[[:xdigit:]]{64}\z/) }
+        info("[Docker] Packaged #{instance.name} as #{name}#{" (#{image_id})" if image_id}")
+      end
+
+      # Checks the configuration and the daemon it points at.
+      #
+      # Run by `kitchen doctor`. A true return is how Test Kitchen decides to
+      # exit non-zero, so every check runs and the results are OR-ed together
+      # rather than returning at the first problem -- somebody running `doctor`
+      # wants the whole list, not the first item on it.
+      #
+      # @param state [Hash] instance state
+      # @return [Boolean] whether a problem was found
+      def doctor(state)
+        [
+          doctor_daemon,
+          doctor_files,
+          doctor_container(state),
+        ].any?
+      end
+
+      # Reports whether the container backing this instance is up.
+      #
+      # Read by `kitchen list --live`, which showed "unknown" for every
+      # instance: {Kitchen::Driver::Base} cannot know, and this driver never
+      # said. Docker can answer directly, and these are the same two questions
+      # create and destroy already ask.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [Hash] normalized status data
+      def status(state)
+        common = { source: "driver", checked_at: Time.now.utc.iso8601, resource_id: state[:container_id] }
+
+        if !state[:container_id]
+          common.merge(live: false, state: "not created",
+            message: "No container is recorded in the state file")
+        elsif !container_exists?(state)
+          common.merge(live: false, state: "gone",
+            message: "The state file names a container the daemon does not have")
+        elsif container_running?(state)
+          common.merge(live: true, state: "running")
+        else
+          common.merge(live: false, state: "stopped",
+            message: "The container exists but is not running")
+        end
+      end
+
       # Waits for the transport to accept a connection, unless disabled.
       #
       # @param state [Hash] instance state describing how to connect
@@ -171,6 +256,44 @@ module Kitchen
 
       protected
 
+      # @return [Boolean] whether the daemon could not be reached
+      def doctor_daemon
+        version = docker_command("version --format '{{.Server.Version}}'", suppress_output: true).strip
+        info("Docker daemon at #{config[:socket]} is reachable, running #{version}.")
+        false
+      rescue => e
+        error("Cannot reach the Docker daemon at #{config[:socket]}. #{e}")
+        true
+      end
+
+      # Checks paths the configuration names.
+      #
+      # A missing TLS file or Dockerfile is worth catching here because docker
+      # reports it far from the cause -- a missing client certificate surfaces
+      # as a connection error rather than as a missing file.
+      #
+      # @return [Boolean] whether any named path is missing
+      def doctor_files
+        %i{tls_cacert tls_cert tls_key dockerfile}.map do |key|
+          path = config[key]
+          next false if path.nil? || ::File.exist?(::File.expand_path(path))
+
+          error("#{key} is set to #{path}, which does not exist.")
+          true
+        end.any?
+      end
+
+      # @param state [Hash] instance state naming the container
+      # @return [Boolean] whether state names a container that is gone
+      def doctor_container(state)
+        return false unless state[:container_id]
+        return false if container_exists?(state)
+
+        error("The state file names container #{state[:container_id]}, which the daemon does " \
+              "not have. Run `kitchen destroy` to clear it.")
+        true
+      end
+
       # The container implementation for this platform.
       #
       # @return [Kitchen::Docker::Container] a Windows or Linux container

data/lib/kitchen/transport/docker.rb

@@ -38,12 +38,14 @@ module Kitchen
       default_config :env_variables, nil
       default_config :interactive,   false
       default_config :privileged,    false
+      default_config :sudo_command,  nil
       default_config :tls,           false
       default_config :tls_cacert,    nil
       default_config :tls_cert,      nil
       default_config :tls_key,       nil
       default_config :tls_verify,    false
       default_config :tty,           false
+      default_config :use_sudo,      false
       default_config :working_dir,   nil
 
       default_config :socket do |transport|

data/spec/cli_helper_spec.rb

@@ -298,6 +298,55 @@ describe Kitchen::Docker::Helpers::CliHelper do
     end
   end
 
+  describe "#docker_command" do
+    # `binary` is set to `echo` and `sudo_command` to `echo SUDO`, so the
+    # assembled command line is observable as output without needing real
+    # sudo -- or a real docker -- on the machine running the specs.
+    def echoed(config = {})
+      helper({ binary: "echo", socket: nil, sudo_command: "echo SUDO" }.merge(config))
+        .docker_command("ps -a")
+    end
+
+    it "runs the command as the invoking user by default" do
+      expect(echoed).to eq "ps -a\n"
+    end
+
+    # Cases from the README's "Permission denied talking to the daemon"
+    # advice. `use_sudo` reached only the `verify_dependencies` probe, so
+    # every command that actually touches the daemon still ran unprivileged
+    # and the documented fix did nothing.
+    it "runs the command through sudo when use_sudo is set" do
+      expect(echoed(use_sudo: true)).to eq "SUDO echo ps -a\n"
+    end
+
+    it "leaves the sudo command at its default when none is configured" do
+      expect(helper(binary: "echo", socket: nil, use_sudo: true).docker_sudo_opts({}))
+        .to eq(use_sudo: true)
+    end
+  end
+
+  describe "#docker_sudo_opts" do
+    it "adds nothing when use_sudo is unset" do
+      expect(helper.docker_sudo_opts(suppress_output: true)).to eq(suppress_output: true)
+    end
+
+    it "adds the sudo options the shell-out layer reads" do
+      expect(helper(use_sudo: true, sudo_command: "doas").docker_sudo_opts({}))
+        .to eq(use_sudo: true, sudo_command: "doas")
+    end
+
+    it "keeps the options it was given" do
+      expect(helper(use_sudo: true).docker_sudo_opts(suppress_output: true))
+        .to eq(suppress_output: true, use_sudo: true)
+    end
+
+    it "does not mutate the options it was given" do
+      options = {}
+      helper(use_sudo: true).docker_sudo_opts(options)
+      expect(options).to eq({})
+    end
+  end
+
   describe "#docker_shell_opts" do
     it "translates suppress_output into silencing the live stream" do
       expect(helper.docker_shell_opts(suppress_output: true)).to eq(live_stream: nil)

data/spec/container_helper_spec.rb

@@ -334,11 +334,80 @@ describe Kitchen::Docker::Helpers::ContainerHelper do
   end
 
   describe "#copy_file_to_container" do
+    let(:state) { { container_id: "abc", platform: "ubuntu-24.04" } }
+
+    # Records every docker subcommand, and answers the copy check with
+    # `landed`. `docker cp` itself prints nothing on success, so the probe is
+    # the only call whose output matters.
+    def copier(landed:)
+      helper.tap do |h|
+        @commands = []
+        allow(h).to receive(:replace_env_variables) { |_s, path| path }
+        allow(h).to receive(:docker_command) do |cmd, _opts = {}|
+          @commands << cmd
+          cmd.include?(described_class::COPIED_MARKER) && landed ? "#{described_class::COPIED_MARKER}\n" : ""
+        end
+      end
+    end
+
     it "addresses the destination as container:path" do
-      h = helper
-      allow(h).to receive(:replace_env_variables) { |_state, path| path }
-      expect(h).to receive(:docker_command).with("cp /local/f.rb abc:/tmp/f.rb")
-      h.copy_file_to_container({ container_id: "abc", platform: "ubuntu-24.04" }, "/local/f.rb", "/tmp/f.rb")
+      copier(landed: true).copy_file_to_container(state, "/local/f.rb", "/tmp/f.rb")
+      expect(@commands.first).to eq "cp /local/f.rb abc:/tmp/f.rb"
+    end
+
+    it "says nothing when the file arrived" do
+      expect { copier(landed: true).copy_file_to_container(state, "/local/f.rb", "/tmp/f.rb") }
+        .not_to raise_error
+    end
+
+    # From #387. `docker cp` writes to the container's filesystem layer, which
+    # a tmpfs or volume mounted over the destination then hides -- and it exits
+    # 0, so nothing about the copy says it did not happen. Left unchecked the
+    # first sign is the next command failing with "No such file or directory",
+    # which names neither the copy nor the mount.
+    context "when docker exits 0 but wrote nothing, as it does into a mount" do
+      it "fails at the copy rather than somewhere later" do
+        expect { copier(landed: false).copy_file_to_container(state, "/local/f.rb", "/tmp/f.rb") }
+          .to raise_error(RuntimeError, %r{Failed to copy file /local/f\.rb})
+      end
+
+      it "names the mount as the cause" do
+        expect { copier(landed: false).copy_file_to_container(state, "/local/f.rb", "/tmp/f.rb") }
+          .to raise_error(RuntimeError, /cannot write into a mount/)
+      end
+
+      it "names the settings that move the destination off the mount" do
+        expect { copier(landed: false).copy_file_to_container(state, "/local/f.rb", "/tmp/f.rb") }
+          .to raise_error(RuntimeError, /temp_dir.*root_path/m)
+      end
+    end
+
+    it "checks the path docker copies into, not the directory it was given" do
+      copier(landed: true).copy_file_to_container(state, "/local/f.rb", "/tmp")
+      # The probe is handed both parts and picks between them inside the
+      # container, since only there is it known whether /tmp is a directory.
+      expect(@commands.last).to include("/tmp f.rb")
+    end
+
+    it "does not print the probe's marker to the console" do
+      h = copier(landed: true)
+      allow(h).to receive(:logger).and_return(double(debug?: false, debug: nil))
+      opts = []
+      allow(h).to receive(:docker_command) { |_cmd, o = {}| opts << o; "" }
+      begin
+        h.copy_file_to_container(state, "/local/f.rb", "/tmp/f.rb")
+      rescue RuntimeError
+        nil
+      end
+      expect(opts.last).to eq(suppress_output: true)
+    end
+
+    # Windows containers have no tmpfs, and `docker cp` against them is a
+    # different code path in Docker, so they keep the behaviour they had.
+    it "does not probe a Windows container" do
+      h = copier(landed: false)
+      h.copy_file_to_container({ container_id: "abc", platform: "windows-2022" }, "C:\\f.rb", "C:\\Temp")
+      expect(@commands.length).to eq 1
     end
   end
 end

data/spec/docker_spec.rb

@@ -62,6 +62,159 @@ describe Kitchen::Driver::Docker do
     end # /context with a hash of strings with spaces
   end # /describe #config_to_options
 
+  # `kitchen package`, `kitchen doctor`, and `kitchen list --live` each ask the
+  # driver a question. Driver::Base answers all three with a shrug, and this
+  # driver used to inherit that: package produced nothing, doctor said nothing,
+  # and every instance listed as "unknown". Docker can answer all three.
+  def driver(config = {}, instance_name: "default-ubuntu-2404")
+    described_class.new(config).tap do |d|
+      allow(d).to receive(:instance).and_return(instance_double("Kitchen::Instance", name: instance_name))
+      allow(d).to receive(:logger).and_return(double(debug?: false, debug: nil))
+      %i{info error debug banner}.each { |level| allow(d).to receive(level) }
+    end
+  end
+
+  describe "#status" do
+    let(:state) { { container_id: "abc123abc123" } }
+
+    def status_of(exists:, running:, state: { container_id: "abc123abc123" })
+      d = driver
+      allow(d).to receive(:container_exists?).and_return(exists)
+      allow(d).to receive(:container_running?).and_return(running)
+      d.status(state)
+    end
+
+    it "reports a running container as live" do
+      expect(status_of(exists: true, running: true))
+        .to include(live: true, state: "running", source: "driver")
+    end
+
+    it "distinguishes a stopped container from a missing one" do
+      expect(status_of(exists: true, running: false)).to include(live: false, state: "stopped")
+      expect(status_of(exists: false, running: false)).to include(live: false, state: "gone")
+    end
+
+    it "reports an instance with no container as not created" do
+      expect(status_of(exists: false, running: false, state: {}))
+        .to include(live: false, state: "not created")
+    end
+
+    it "names the container so `kitchen list --live` can show it" do
+      expect(status_of(exists: true, running: true)[:resource_id]).to eq "abc123abc123"
+    end
+
+    it "does not ask docker about an instance that has no container" do
+      d = driver
+      expect(d).not_to receive(:container_exists?)
+      d.status({})
+    end
+
+    it "stamps when it looked" do
+      expect(status_of(exists: true, running: true)[:checked_at])
+        .to match(/\A\d{4}-\d{2}-\d{2}T[\d:]+Z\z/)
+    end
+  end
+
+  describe "#package" do
+    let(:state) { { container_id: "abc123abc123" } }
+    let(:digest) { "sha256:#{"a" * 64}" }
+
+    it "commits the container to the configured image name" do
+      d = driver({ package_name: "myapp:v1" })
+      allow(d).to receive(:container_exists?).and_return(true)
+      expect(d).to receive(:docker_command)
+        .with("commit abc123abc123 myapp:v1", hash_including(:suppress_output))
+        .and_return("#{digest}\n")
+      d.package(state)
+    end
+
+    it "names the image after the instance by default" do
+      d = driver
+      expect(d.send(:config)[:package_name]).to eq "default-ubuntu-2404:latest"
+    end
+
+    it "escapes a package name that would otherwise split" do
+      d = driver({ package_name: "my app:v1" })
+      allow(d).to receive(:container_exists?).and_return(true)
+      expect(d).to receive(:docker_command)
+        .with(%q{commit abc123abc123 my\ app:v1}, hash_including(:suppress_output))
+        .and_return("#{digest}\n")
+      d.package(state)
+    end
+
+    it "refuses to package an instance that was never created" do
+      expect { driver.package({}) }
+        .to raise_error(Kitchen::ActionFailed, /has not been created/)
+    end
+
+    it "does not run docker for an instance that was never created" do
+      d = driver
+      expect(d).not_to receive(:docker_command)
+      expect { d.package({}) }.to raise_error(Kitchen::ActionFailed)
+    end
+
+    # `docker commit` on a container that is gone says only "Error response
+    # from daemon: No such container: <64 hex characters>", which names neither
+    # the instance nor what to do about it.
+    it "names the instance when the container is gone" do
+      d = driver
+      allow(d).to receive(:container_exists?).and_return(false)
+      expect { d.package(state) }
+        .to raise_error(Kitchen::ActionFailed, /default-ubuntu-2404.*kitchen destroy/m)
+    end
+  end
+
+  describe "#doctor" do
+    let(:state) { {} }
+
+    def doctor_with(config = {}, daemon: "29.7.2", state: {})
+      d = driver(config)
+      allow(d).to receive(:container_exists?).and_return(true)
+      allow(d).to receive(:docker_command) do
+        raise Kitchen::ShellOut::ShellCommandFailed, "cannot connect" if daemon.nil?
+
+        "#{daemon}\n"
+      end
+      d.doctor(state)
+    end
+
+    it "reports no problem when the daemon answers" do
+      expect(doctor_with).to be false
+    end
+
+    it "reports a problem when the daemon cannot be reached" do
+      expect(doctor_with(daemon: nil)).to be true
+    end
+
+    it "reports a TLS file that is not there" do
+      expect(doctor_with({ tls_cert: "/nope/cert.pem" })).to be true
+    end
+
+    it "reports a dockerfile that is not there" do
+      expect(doctor_with({ dockerfile: "/nope/Dockerfile" })).to be true
+    end
+
+    it "accepts paths that do exist" do
+      expect(doctor_with({ dockerfile: __FILE__ })).to be false
+    end
+
+    it "reports a state file naming a container the daemon does not have" do
+      d = driver
+      allow(d).to receive(:docker_command).and_return("29.7.2\n")
+      allow(d).to receive(:container_exists?).and_return(false)
+      expect(d.doctor(container_id: "abc123abc123")).to be true
+    end
+
+    it "keeps checking after the first problem, so the whole list is reported" do
+      # `kitchen doctor` exists to tell you everything that is wrong at once.
+      d = driver({ tls_cert: "/nope/cert.pem", dockerfile: "/nope/Dockerfile" })
+      allow(d).to receive(:docker_command).and_raise(Kitchen::ShellOut::ShellCommandFailed, "nope")
+      allow(d).to receive(:container_exists?).and_return(false)
+      expect(d).to receive(:error).at_least(4).times
+      d.doctor(container_id: "abc123abc123")
+    end
+  end
+
   describe "socket default config logic" do
     def resolve_socket
       socket = "unix:///var/run/docker.sock"

data/spec/image_helper_spec.rb

@@ -178,4 +178,49 @@ describe Kitchen::Docker::Helpers::ImageHelper do
       h.remove_image(state)
     end
   end
+
+  describe "#image_exists?" do
+    let(:state) { { image_id: "sha256:abc" } }
+
+    def asking(&answer)
+      helper.tap do |h|
+        @opts = nil
+        allow(h).to receive(:logger).and_return(double(debug?: false, debug: nil))
+        allow(h).to receive(:docker_command) { |_cmd, opts = {}| @opts = opts; answer.call }
+      end
+    end
+
+    it "is true when docker knows the image" do
+      expect(asking { "[{}]" }.image_exists?(state)).to be true
+    end
+
+    it "is false when docker does not" do
+      expect(asking { raise Kitchen::ShellOut::ShellCommandFailed, "no such image" }
+        .image_exists?(state)).to be false
+    end
+
+    it "does not ask about an image that state does not name" do
+      h = helper
+      expect(h).not_to receive(:docker_command)
+      expect(h.image_exists?({})).to be false
+    end
+
+    # `kitchen destroy` with remove_images set printed the image's whole
+    # inspect JSON -- config, every layer digest, metadata -- between removing
+    # the container and removing the image. Only whether the command succeeded
+    # is used here, as in every other predicate in this file, all of which
+    # already silence their output.
+    it "does not print the inspect output" do
+      asking { "[{}]" }.image_exists?(state)
+      expect(@opts).to eq(suppress_output: true)
+    end
+
+    it "still prints it under -l debug" do
+      h = helper
+      allow(h).to receive(:logger).and_return(double(debug?: true, debug: nil))
+      allow(h).to receive(:docker_command) { |_cmd, opts = {}| @opts = opts; "[{}]" }
+      h.image_exists?(state)
+      expect(@opts).to eq(suppress_output: false)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-docker
 version: !ruby/object:Gem::Version
-  version: 3.3.4
+  version: 3.4.0
 platform: ruby
 authors:
 - Sean Porter
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'