kitchen-docker 3.3.1 → 3.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48b3e240f091225e997ef1b3ef22576733a2874ea3584e2d362f84af9bf48d70
-  data.tar.gz: d1f6e04ee6c62a9bdcd95f7020ce63b7de932161486383b2cde9d0541f871eab
+  metadata.gz: f64096aa934f3502dd1427249a5d15db1371855534522ecb20b4ea4e928f7a5b
+  data.tar.gz: 013667f1b55015399185c490cae0c3cd5e899e9fb8678af3fcb42d74c5c9e5d8
 SHA512:
-  metadata.gz: 2aab821262b74c69f39e6189549d87e9bbb265e9a9169d318702d86f0504c719e777a8363726e9996727b31c7b3ab989c5c1b917d641915b39268952114c57c9
-  data.tar.gz: f02acc355ec6699a2a23557d39599b1c98be400e906b9bfc20ee8dfa330c4d3eb98cbde1f8ccb38bcbab5ff8cd166ccf9babac0864a44fa1d7fbb8eaad78edaf
+  metadata.gz: 414439ff16eeffb9f0288925cd6579da33f60968efe4ead0fa85d6454d98499f634dfed7bfe90ff2131c2a519c2b5f109fdefd7cb854a917f7ff756f539a7f24
+  data.tar.gz: 72446a19d4951a3b1b87b66a3c604f13f67cac6395588e1698c4a9dc4ab7cd8f9f3edaa31c1c5ecc7ed5477a26a0e40639d217290ae48c74fb368daadc555b45

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.3.1"
+  ".": "3.3.3"
 }

data/CHANGELOG.md

@@ -6,6 +6,25 @@ 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.3.3](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.2...v3.3.3) (2026-08-23)
+
+
+### Bug Fixes
+
+* detect containers that exist but have stopped ([#476](https://github.com/test-kitchen/kitchen-docker/issues/476)) ([c6c7038](https://github.com/test-kitchen/kitchen-docker/commit/c6c70382f9e7be4a4c27f5f225f72465a3b392a6))
+* detect that an image is in use before removing it ([#477](https://github.com/test-kitchen/kitchen-docker/issues/477)) ([4c5f255](https://github.com/test-kitchen/kitchen-docker/commit/4c5f255bdcbbb58c9f8b4e225627642d6ac79fed))
+* remove the staged script when a command fails ([#481](https://github.com/test-kitchen/kitchen-docker/issues/481)) ([44de85e](https://github.com/test-kitchen/kitchen-docker/commit/44de85e9ac552b317bf116248d80c3d9c1a81dd0))
+* report why a temp file could not be written ([#480](https://github.com/test-kitchen/kitchen-docker/issues/480)) ([70565e5](https://github.com/test-kitchen/kitchen-docker/commit/70565e56d0755791596920a55bd4f5897a1dc455))
+
+## [3.3.2](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.1...v3.3.2) (2026-08-23)
+
+
+### Bug Fixes
+
+* escape configured values interpolated into docker command lines ([#471](https://github.com/test-kitchen/kitchen-docker/issues/471)) ([994b0ca](https://github.com/test-kitchen/kitchen-docker/commit/994b0ca9d89bab0501b3946ca45fd177b24bf2bd))
+* split printenv output on the first equals sign only ([#473](https://github.com/test-kitchen/kitchen-docker/issues/473)) ([9b0d0d7](https://github.com/test-kitchen/kitchen-docker/commit/9b0d0d784efe4f65c1c6585e19440e90e322b3a1))
+* tolerate stderr warnings when parsing docker run container id (rebase of [#452](https://github.com/test-kitchen/kitchen-docker/issues/452)) ([#475](https://github.com/test-kitchen/kitchen-docker/issues/475)) ([a8ad6f6](https://github.com/test-kitchen/kitchen-docker/commit/a8ad6f6e05e927f3966a72ee6029b9f135246565))
+
 ## [3.3.1](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.0...v3.3.1) (2026-08-23)
 
 

data/lib/kitchen/docker/container/linux.rb

@@ -80,9 +80,6 @@ module Kitchen
           debug("Uploading temp file #{temp_file} to #{remote_path} on container")
           upload(temp_file, remote_path)
 
-          debug("Deleting temp file from local filesystem")
-          ::File.delete(temp_file)
-
           # Replace any environment variables used in the path and execute script file
           debug("Executing temp script #{remote_path}/#{filename} on container")
           remote_path = replace_env_variables(@config, remote_path)
@@ -90,6 +87,13 @@ module Kitchen
           container_exec(@config, "/bin/bash #{remote_path}/#{filename}")
         rescue => e
           raise "Failed to execute command on Linux container. #{e}"
+        ensure
+          # Removed here rather than after the upload, so that a failure part
+          # way through does not leave the script behind in .kitchen/temp.
+          if temp_file && ::File.exist?(temp_file)
+            debug("Deleting temp file from local filesystem")
+            ::File.delete(temp_file)
+          end
         end
 
         protected
@@ -120,14 +124,27 @@ module Kitchen
 
         # Pulls the published port out of `docker port` output.
         #
-        # @param output [String] e.g. +"0.0.0.0:32768"+
+        # One line is printed per published binding, and the host part varies:
+        #
+        #   0.0.0.0:32768
+        #   [::]:32768
+        #
+        # The port is taken from the end of the line rather than by splitting on
+        # ":" from the left, because an IPv6 host contains colons of its own --
+        # splitting left-to-right returned "" for those, and "".to_i is 0, so a
+        # daemon publishing on IPv6 handed Test Kitchen port 0 to connect to.
+        #
+        # @param output [String] e.g. +"0.0.0.0:32768\n[::]:32768\n"+
         # @return [Integer] the host-side port
-        # @raise [Kitchen::ActionFailed] if the output cannot be parsed
+        # @raise [Kitchen::ActionFailed] if no port could be found
         def parse_container_ssh_port(output)
-          _host, port = output.split(":")
+          port = output.lines.filter_map { |line| line[/:(\d+)\s*\z/, 1] }.first
+
+          if port.nil?
+            raise ActionFailed, "Could not parse Docker port output for container SSH port: #{output.inspect}"
+          end
+
           port.to_i
-        rescue => e
-          raise ActionFailed, "Could not parse Docker port output for container SSH port. #{e}"
         end
 
         # The port Test Kitchen should connect to for SSH.

data/lib/kitchen/docker/container/windows.rb

@@ -66,9 +66,6 @@ module Kitchen
           debug("Uploading temp file #{temp_file} to #{remote_path} on container")
           upload(temp_file, remote_path)
 
-          debug("Deleting temp file from local filesystem")
-          ::File.delete(temp_file)
-
           # Replace any environment variables used in the path and execute script file
           debug("Executing temp script #{remote_path}\\#{filename} on container")
           remote_path = replace_env_variables(@config, remote_path)
@@ -77,6 +74,13 @@ module Kitchen
           container_exec(@config, cmd)
         rescue => e
           raise "Failed to execute command on Windows container. #{e}"
+        ensure
+          # Removed here rather than after the upload, so that a failure part
+          # way through does not leave the script behind in .kitchen/temp.
+          if temp_file && ::File.exist?(temp_file)
+            debug("Deleting temp file from local filesystem")
+            ::File.delete(temp_file)
+          end
         end
 
         protected

data/lib/kitchen/docker/container.rb

@@ -42,13 +42,23 @@ module Kitchen
       # container was removed behind Test Kitchen's back and silently creating a
       # new one would hide that.
       #
+      # A container that exists but has stopped is also an error, and a separate
+      # one: it is still there to be cleaned up, so the message points at
+      # `kitchen destroy` rather than claiming the container is gone.
+      #
       # @param state [Hash] mutable instance state; gains +username+
       # @return [void]
-      # @raise [Kitchen::ActionFailed] if state names a container that is gone
+      # @raise [Kitchen::ActionFailed] if state names a container that is gone,
+      #   or one that exists but is not running
       def create(state)
         if container_exists?(state)
+          unless container_running?(state)
+            raise ActionFailed, "Container ID #{state[:container_id]} was found in the kitchen state data, " \
+                                "but the container is not running. Run `kitchen destroy` to remove it."
+          end
+
           info("Container ID #{state[:container_id]} already exists.")
-        elsif !container_exists?(state) && state[:container_id]
+        elsif state[:container_id]
           raise ActionFailed, "Container ID #{state[:container_id]} was found in the kitchen state data, " \
                               "but the container does not exist."
         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.1".freeze
+    DOCKER_VERSION = "3.3.3".freeze
   end
 end

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

@@ -15,6 +15,7 @@ require "kitchen"
 require "kitchen/configurable"
 require "kitchen/logging"
 require "kitchen/shell_out"
+require "shellwords" unless defined?(Shellwords)
 
 module Kitchen
   module Docker
@@ -27,6 +28,27 @@ module Kitchen
         include Logging
         include ShellOut
 
+        # Escapes a configured value for the shell.
+        #
+        # Docker command lines are assembled as strings and handed to a shell, so
+        # a value that is a single datum -- a path, a name, a port mapping -- has
+        # to be escaped, or a space inside it is read as an argument separator and
+        # the rest of the value is taken as the image name.
+        #
+        # Values that are deliberately shell fragments are *not* escaped:
+        # +run_command+, +run_options+, +build_options+, and the command handed to
+        # `docker exec` are all documented as accepting flags and arguments.
+        #
+        # Escaping is a no-op for ordinary values -- +db:db+ and +8.8.8.8+ come
+        # back unchanged -- so this only alters command lines that were already
+        # broken.
+        #
+        # @param value [#to_s] the configured value
+        # @return [String] the value, safe to interpolate into a command line
+        def shell_escape(value)
+          Shellwords.escape(value.to_s)
+        end
+
         # rubocop:disable Metrics/AbcSize
 
         # Runs a docker CLI command with the configured connection flags.
@@ -36,12 +58,12 @@ module Kitchen
         # @return [String] the command's combined stdout and stderr
         def docker_command(cmd, options = {})
           docker = config[:binary].dup
-          docker << " -H #{config[:socket]}" if config[:socket]
+          docker << " -H #{shell_escape(config[:socket])}" if config[:socket]
           docker << " --tls" if config[:tls]
           docker << " --tlsverify" if config[:tls_verify]
-          docker << " --tlscacert=#{config[:tls_cacert]}" if config[:tls_cacert]
-          docker << " --tlscert=#{config[:tls_cert]}" if config[:tls_cert]
-          docker << " --tlskey=#{config[:tls_key]}" if config[:tls_key]
+          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]
           logger.debug("docker_command: #{docker} #{cmd} shell_opts: #{docker_shell_opts(options)}")
           run_command("#{docker} #{cmd}", docker_shell_opts(options))
         end
@@ -91,32 +113,33 @@ module Kitchen
           cmd << " -t" if config[:tty]
           cmd << build_env_variable_args(config[:env_variables]) if config[:env_variables]
           cmd << " -p #{transport_port}" unless transport_port.nil?
-          Array(config[:forward]).each { |port| cmd << " -p #{port}" }
-          Array(config[:dns]).each { |dns| cmd << " --dns #{dns}" }
-          Array(config[:add_host]).each { |host, ip| cmd << " --add-host=#{host}:#{ip}" }
-          Array(config[:volume]).each { |volume| cmd << " -v #{volume}" }
-          Array(config[:volumes_from]).each { |container| cmd << " --volumes-from #{container}" }
-          Array(config[:links]).each { |link| cmd << " --link #{link}" }
-          Array(config[:devices]).each { |device| cmd << " --device #{device}" }
-          Array(config[:mount]).each { |mount| cmd << " --mount #{mount}" }
-          Array(config[:tmpfs]).each { |tmpfs| cmd << " --tmpfs #{tmpfs}" }
-          cmd << " --name #{config[:instance_name]}" if config[:instance_name]
+          Array(config[:forward]).each { |port| cmd << " -p #{shell_escape(port)}" }
+          Array(config[:dns]).each { |dns| cmd << " --dns #{shell_escape(dns)}" }
+          Array(config[:add_host]).each { |host, ip| cmd << " --add-host=#{shell_escape("#{host}:#{ip}")}" }
+          Array(config[:volume]).each { |volume| cmd << " -v #{shell_escape(volume)}" }
+          Array(config[:volumes_from]).each { |container| cmd << " --volumes-from #{shell_escape(container)}" }
+          Array(config[:links]).each { |link| cmd << " --link #{shell_escape(link)}" }
+          Array(config[:devices]).each { |device| cmd << " --device #{shell_escape(device)}" }
+          Array(config[:mount]).each { |mount| cmd << " --mount #{shell_escape(mount)}" }
+          Array(config[:tmpfs]).each { |tmpfs| cmd << " --tmpfs #{shell_escape(tmpfs)}" }
+          cmd << " --name #{shell_escape(config[:instance_name])}" if config[:instance_name]
           cmd << " -P" if config[:publish_all]
-          cmd << " -h #{config[:hostname]}" if config[:hostname]
-          cmd << " -m #{config[:memory]}" if config[:memory]
-          cmd << " -c #{config[:cpu]}" if config[:cpu]
-          cmd << " --gpus #{config[:gpus]}" if config[:gpus]
-          cmd << " -e http_proxy=#{config[:http_proxy]}" if config[:http_proxy]
-          cmd << " -e https_proxy=#{config[:https_proxy]}" if config[:https_proxy]
+          cmd << " -h #{shell_escape(config[:hostname])}" if config[:hostname]
+          cmd << " -m #{shell_escape(config[:memory])}" if config[:memory]
+          cmd << " -c #{shell_escape(config[:cpu])}" if config[:cpu]
+          cmd << " --gpus #{shell_escape(config[:gpus])}" if config[:gpus]
+          cmd << " -e http_proxy=#{shell_escape(config[:http_proxy])}" if config[:http_proxy]
+          cmd << " -e https_proxy=#{shell_escape(config[:https_proxy])}" if config[:https_proxy]
           cmd << " --privileged" if config[:privileged]
-          cmd << " --isolation #{config[:isolation]}" if config[:isolation]
-          Array(config[:cap_add]).each { |cap| cmd << " --cap-add=#{cap}" } if config[:cap_add]
-          Array(config[:cap_drop]).each { |cap| cmd << " --cap-drop=#{cap}" } if config[:cap_drop]
-          Array(config[:security_opt]).each { |opt| cmd << " --security-opt=#{opt}" } if config[:security_opt]
-          cmd << " --platform=#{config[:docker_platform]}" if config[:docker_platform]
+          cmd << " --isolation #{shell_escape(config[:isolation])}" if config[:isolation]
+          Array(config[:cap_add]).each { |cap| cmd << " --cap-add=#{shell_escape(cap)}" } if config[:cap_add]
+          Array(config[:cap_drop]).each { |cap| cmd << " --cap-drop=#{shell_escape(cap)}" } if config[:cap_drop]
+          Array(config[:security_opt]).each { |opt| cmd << " --security-opt=#{shell_escape(opt)}" } if config[:security_opt]
+          cmd << " --platform=#{shell_escape(config[:docker_platform])}" if config[:docker_platform]
           extra_run_options = config_to_options(config[:run_options])
           cmd << " #{extra_run_options}" unless extra_run_options.empty?
-          cmd << " #{image_id} #{config[:run_command]}"
+          # run_command is a command line, not a single value, so it stays raw.
+          cmd << " #{shell_escape(image_id)} #{config[:run_command]}"
           logger.debug("build_run_command: #{cmd}")
           cmd
         end
@@ -136,9 +159,10 @@ module Kitchen
           cmd << " --privileged" if config[:privileged]
           cmd << " -t" if config[:tty]
           cmd << " -i" if config[:interactive]
-          cmd << " -u #{config[:username]}" if config[:username]
-          cmd << " -w #{config[:working_dir]}" if config[:working_dir]
-          cmd << " #{state[:container_id]}"
+          cmd << " -u #{shell_escape(config[:username])}" if config[:username]
+          cmd << " -w #{shell_escape(config[:working_dir])}" if config[:working_dir]
+          cmd << " #{shell_escape(state[:container_id])}"
+          # command is a command line, not a single value, so it stays raw.
           cmd << " #{command}"
           logger.debug("build_exec_command: #{cmd}")
           cmd
@@ -154,7 +178,7 @@ module Kitchen
         def build_copy_command(local_file, remote_file, opts = {})
           cmd = "cp"
           cmd << " -a" if opts[:archive]
-          cmd << " #{local_file} #{remote_file}"
+          cmd << " #{shell_escape(local_file)} #{shell_escape(remote_file)}"
           cmd
         end
 
@@ -179,7 +203,7 @@ module Kitchen
 
           args = ""
           vars.each do |k, v|
-            args << " -e #{k.to_s.strip}=\"#{v.to_s.strip}\""
+            args << " -e #{shell_escape("#{k.to_s.strip}=#{v.to_s.strip}")}"
           end
 
           args

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

@@ -34,19 +34,31 @@ module Kitchen
 
         # Pulls the container id out of `docker run` output.
         #
-        # Docker prints ids in short (12) or full (64) hex form; anything else
-        # means the output was not an id at all.
+        # Docker prints ids in short (12) or full (64) hex form, on a line of
+        # their own. The id is looked for line by line rather than by taking the
+        # whole output, because {CliHelper#run_command} returns stdout and stderr
+        # together and some daemons write warnings to stderr on a run that
+        # otherwise succeeds. Rootless Docker emits "WARNING: IPv4 forwarding is
+        # disabled. Networking will not work." on every run; setting
+        # +run_options+ to +--net=host+ produces "WARNING: Published ports are
+        # discarded when using host network mode", since the driver always
+        # publishes port 22 for Linux containers. Treating the whole output as
+        # the id failed those runs *after* the container had been created,
+        # leaving it running and untracked.
         #
-        # @param output [String] the command output
+        # Scanning forward is deterministic: +run_command+ concatenates stdout
+        # before stderr, so the id always precedes anything a warning adds.
+        #
+        # @param output [String] the command output, stdout and stderr together
         # @return [String] the container id
-        # @raise [Kitchen::ActionFailed] if no id could be parsed
+        # @raise [Kitchen::ActionFailed] if no id could be found
         def parse_container_id(output)
-          container_id = output.chomp
-
-          unless [12, 64].include?(container_id.size)
-            raise ActionFailed, "Could not parse Docker run output for container ID"
+          container_id = output.to_s.lines.map(&:strip).find do |line|
+            line.match?(/\A[0-9a-f]{12}(?:[0-9a-f]{52})?\z/)
           end
 
+          raise ActionFailed, "Could not parse Docker run output for container ID" unless container_id
+
           container_id
         end
 
@@ -81,10 +93,45 @@ module Kitchen
           config[:build_context] ? Pathname.new(file.path).relative_path_from(Pathname.pwd).to_s : file.path
         end
 
+        # Whether the container named in state is present, running or not.
+        #
+        # Asked with `docker inspect` rather than `docker top`, which answers a
+        # different question: `top` lists processes, so it fails on a container
+        # that exists but has stopped. Reading that as "does not exist" made
+        # {Kitchen::Docker::Container#destroy} skip removal and leave the
+        # container behind, while Test Kitchen deleted the state file and
+        # reported success.
+        #
         # @param state [Hash] instance state naming the container
-        # @return [Boolean] whether the container is present and running
+        # @return [Boolean] whether the container exists in any state
         def container_exists?(state)
-          state[:container_id] && !!docker_command("top #{state[:container_id]}") rescue false
+          return false unless state[:container_id]
+
+          !!docker_command("inspect --type=container #{state[:container_id]}",
+            suppress_output: !logger.debug?)
+        rescue
+          false
+        end
+
+        # Whether the container named in state is running.
+        #
+        # Separate from {#container_exists?} because the two callers want
+        # different questions answered: destroy removes a container in any
+        # state, while create has to tell a container it can use from one that
+        # has stopped.
+        #
+        # @param state [Hash] instance state naming the container
+        # @return [Boolean] whether the container exists and is running
+        def container_running?(state)
+          return false unless state[:container_id]
+
+          output = docker_command(
+            "inspect --type=container --format '{{.State.Running}}' #{state[:container_id]}",
+            suppress_output: !logger.debug?
+          )
+          output.strip == "true"
+        rescue
+          false
         end
 
         # Runs a command inside the container.
@@ -159,7 +206,14 @@ module Kitchen
           else
             cmd = build_exec_command(state, "printenv")
             stdout = docker_command(cmd, suppress_output: !logger.debug?).strip
-            stdout.split("\n").each { |line| vars[line.split("=")[0]] = line.split("=")[1] }
+            # printenv writes NAME=VALUE, and values routinely contain "=" --
+            # LS_COLORS and anything -Dkey=value shaped do. Split on the first
+            # one only, or the value is truncated at it. Lines with no "=" are
+            # continuations of a multi-line value and carry no name.
+            stdout.split("\n").each do |line|
+              name, value = line.split("=", 2)
+              vars[name] = value unless value.nil?
+            end
           end
 
           vars

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

@@ -21,26 +21,32 @@ module Kitchen
       module FileHelper
         # Writes a temp file, creating its parent directory if needed.
         #
+        # Written with +File.write+, which opens, writes and closes in one call.
+        # The previous implementation assigned the open file back over the +file+
+        # parameter and closed it in an +ensure+, so when opening failed -- a
+        # read-only directory, a parent that is not a directory, a full disk --
+        # +file+ was still the path String and the ensure raised
+        # "undefined method 'close' for an instance of String", replacing the
+        # real error with a Ruby one. Its rescue did not help either: it caught
+        # +IOError+, while opening a file fails with +Errno+ classes, which are
+        # +SystemCallError+ and not +IOError+.
+        #
         # @param file [String] path to write
         # @param contents [String] what to write
         # @return [void]
-        # @raise [RuntimeError] if the write fails
+        # @raise [RuntimeError] if the file cannot be written, naming the path
+        #   and the underlying cause
         def create_temp_file(file, contents)
           debug("[Docker] Creating temp file #{file}")
           debug("[Docker] --- Start Temp File Contents ---")
           debug(contents)
           debug("[Docker] --- End Temp File Contents ---")
 
-          begin
-            path = ::File.dirname(file)
-            ::FileUtils.mkdir_p(path) unless ::Dir.exist?(path)
-            file = ::File.open(file, "w")
-            file.write(contents)
-          rescue IOError => e
-            raise "Failed to write temp file. Error Details: #{e}"
-          ensure
-            file.close unless file.nil?
-          end
+          path = ::File.dirname(file)
+          ::FileUtils.mkdir_p(path) unless ::Dir.exist?(path)
+          ::File.write(file, contents)
+        rescue SystemCallError, IOError => e
+          raise "Failed to write temp file #{file}. Error Details: #{e}"
         end
       end
     end

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

@@ -68,10 +68,28 @@ module Kitchen
           end
         end
 
+        # Whether any container was created from the image.
+        #
+        # Asked with a filter rather than by searching `docker ps -a` output for
+        # the id. That output abbreviates the IMAGE column to twelve characters,
+        # while state carries the full +sha256:+ digest, so the substring never
+        # matched and the answer was always false -- which defeated the guard
+        # entirely and let {#remove_image} run `docker rmi` against an image a
+        # container was still using.
+        #
         # @param state [Hash] instance state naming the image
         # @return [Boolean] whether any container references it
         def image_in_use?(state)
-          docker_command("ps -a", suppress_output: !logger.debug?).include?(state[:image_id])
+          return false unless state[:image_id]
+
+          output = docker_command("ps -a -q --filter ancestor=#{state[:image_id]}",
+            suppress_output: !logger.debug?)
+
+          # Matched line by line rather than by emptiness, so a warning docker
+          # writes to stderr is not mistaken for a container id.
+          output.lines.map(&:strip).any? do |line|
+            line.match?(/\A[0-9a-f]{12}(?:[0-9a-f]{52})?\z/)
+          end
         end
 
         # Builds the image from the given Dockerfile.

data/spec/cli_helper_spec.rb

@@ -104,17 +104,14 @@ describe Kitchen::Docker::Helpers::CliHelper do
       # configured value containing a space has to survive shell splitting as a
       # single argument. These are the cases where it does not.
       it "keeps a volume path containing a space as one argument" do
-        pending "BUG: build_run_command interpolates volume unquoted, so a path with a space becomes two arguments"
         expect(run_argv(volume: "/host dir:/data")).to include_consecutive("-v", "/host dir:/data")
       end
 
       it "keeps a hostname containing a space as one argument" do
-        pending "BUG: build_run_command interpolates hostname unquoted"
         expect(run_argv(hostname: "two words")).to include_consecutive("-h", "two words")
       end
 
       it "keeps a mount specification containing a space as one argument" do
-        pending "BUG: build_run_command interpolates mount unquoted"
         expect(run_argv(mount: "type=bind,source=/my dir,destination=/d"))
           .to include_consecutive("--mount", "type=bind,source=/my dir,destination=/d")
       end
@@ -176,10 +173,22 @@ describe Kitchen::Docker::Helpers::CliHelper do
     end
 
     it "keeps a value containing a double quote intact" do
-      pending "BUG: values are wrapped in double quotes, so an embedded double quote ends the quoting early"
       expect(argv(helper.build_env_variable_args("MSG" => 'say "hi"')))
         .to eq ["-e", 'MSG=say "hi"']
     end
+
+    it "keeps a value containing a dollar sign out of the shell's reach" do
+      # An unescaped $HOME would be expanded by the shell running the docker
+      # command, so the container would receive the workstation's home
+      # directory instead of the literal string.
+      expect(argv(helper.build_env_variable_args("P" => "$HOME/x")))
+        .to eq ["-e", "P=$HOME/x"]
+    end
+
+    it "keeps a name containing a space as one argument" do
+      expect(argv(helper.build_env_variable_args("ODD NAME" => "v")))
+        .to eq ["-e", "ODD NAME=v"]
+    end
   end
 
   describe "#build_copy_command" do
@@ -194,7 +203,6 @@ describe Kitchen::Docker::Helpers::CliHelper do
     end
 
     it "keeps a local path containing a space as one argument" do
-      pending "BUG: build_copy_command interpolates both paths unquoted, so uploads from a path with a space fail"
       expect(argv(helper.build_copy_command("/Users/me/My Cookbooks/f.rb", "abc:/tmp/f.rb")))
         .to eq ["cp", "/Users/me/My Cookbooks/f.rb", "abc:/tmp/f.rb"]
     end

data/spec/container_helper_spec.rb

@@ -30,18 +30,64 @@ describe Kitchen::Docker::Helpers::ContainerHelper do
         .to raise_error(Kitchen::ActionFailed, /Could not parse Docker run output/)
     end
 
+    it "fails loudly on empty output" do
+      expect { helper.parse_container_id("") }
+        .to raise_error(Kitchen::ActionFailed, /Could not parse Docker run output/)
+    end
+
+    # Cases from #452. Rootless Docker emits this on every `docker run`, which
+    # makes it the most common way to reach this code path.
+    context "when docker wrote a warning to stderr" do
+      let(:warning) { "WARNING: IPv4 forwarding is disabled. Networking will not work." }
+
+      it "finds an id the warning follows" do
+        expect(helper.parse_container_id("#{DockerOutput::RUN_CONTAINER_ID}\n#{warning}\n"))
+          .to eq DockerOutput::RUN_CONTAINER_ID
+      end
+
+      it "finds an id the warning precedes" do
+        expect(helper.parse_container_id("#{warning}\n#{DockerOutput::RUN_CONTAINER_ID}\n"))
+          .to eq DockerOutput::RUN_CONTAINER_ID
+      end
+
+      it "finds a short id" do
+        expect(helper.parse_container_id("abcdef123456\n#{warning}\n")).to eq "abcdef123456"
+      end
+
+      it "still fails when the warning is all there is" do
+        expect { helper.parse_container_id("#{warning}\nno container id here") }
+          .to raise_error(Kitchen::ActionFailed, /Could not parse Docker run output/)
+      end
+    end
+
+    it "takes the id docker printed, not a later hex line" do
+      # run_command concatenates stdout before stderr, so the id always comes
+      # first. Scanning backwards would prefer a bare hex line that a warning
+      # happened to leave on stderr.
+      expect(helper.parse_container_id("#{DockerOutput::RUN_CONTAINER_ID}\ndeadbeefcafe\n"))
+        .to eq DockerOutput::RUN_CONTAINER_ID
+    end
+
+    it "does not mistake a hex-looking word inside a message for an id" do
+      expect { helper.parse_container_id("WARNING: layer abcdef123456 was skipped\n") }
+        .to raise_error(Kitchen::ActionFailed, /Could not parse Docker run output/)
+    end
+
+    it "tolerates surrounding whitespace on the id line" do
+      expect(helper.parse_container_id("  #{DockerOutput::RUN_CONTAINER_ID}  \n"))
+        .to eq DockerOutput::RUN_CONTAINER_ID
+    end
+
     # run_command returns stdout + stderr, and the parser requires the whole
     # combined string to be exactly the id. Anything docker writes to stderr on
     # a successful `run` therefore fails container creation, with an error that
     # blames parsing rather than naming the warning.
     it "finds the id when docker pulled the image and logged progress to stderr" do
-      pending "BUG: parse_container_id requires the entire output to be the id, so any stderr output fails the run"
       expect(helper.parse_container_id(DockerOutput::RUN_WITH_PULL_ON_STDERR))
         .to eq DockerOutput::RUN_CONTAINER_ID
     end
 
     it "finds the id when the kernel lacks swap accounting" do
-      pending "BUG: the 'No swap limit support' warning docker emits on many Linux hosts is concatenated onto the id"
       expect(helper.parse_container_id(DockerOutput::RUN_WITH_SWAP_WARNING))
         .to eq DockerOutput::RUN_CONTAINER_ID
     end
@@ -110,11 +156,26 @@ describe Kitchen::Docker::Helpers::ContainerHelper do
     # rather than the first silently truncates them, and the truncated value
     # then flows into replace_env_variables and into upload paths.
     it "keeps a value containing an equals sign intact" do
-      pending "BUG: values are split on every '=' rather than the first; use split(\"=\", 2)"
       expect(with_printenv("LS_COLORS=rs=0:di=01;34\n"))
         .to eq("LS_COLORS" => "rs=0:di=01;34")
     end
 
+    it "keeps a value that is itself a key=value list" do
+      expect(with_printenv("JAVA_OPTS=-Dfoo=bar -Dbaz=qux\n"))
+        .to eq("JAVA_OPTS" => "-Dfoo=bar -Dbaz=qux")
+    end
+
+    it "keeps a variable with an empty value" do
+      expect(with_printenv("EMPTY=\n")).to eq("EMPTY" => "")
+    end
+
+    it "ignores a continuation line of a multi-line value" do
+      # printenv prints an embedded newline literally, so the second line has no
+      # name. Recording it would put a nil-valued entry under a bogus key.
+      expect(with_printenv("CERT=-----BEGIN-----\nMIIBIjANBg\n"))
+        .to eq("CERT" => "-----BEGIN-----")
+    end
+
     it "parses the JSON a Windows container returns" do
       h = helper
       allow(h).to receive(:docker_command).and_return('{"TEMP":"C:\\\\Users\\\\ADMINI~1\\\\AppData\\\\Local\\\\Temp"}')
@@ -156,6 +217,59 @@ describe Kitchen::Docker::Helpers::ContainerHelper do
     end
   end
 
+  describe "#container_exists? and #container_running?" do
+    # `docker inspect` answers for a container in any state; `docker top` only
+    # for a running one. The two predicates have to disagree on a stopped
+    # container, or destroy cannot clean it up.
+    def helper_answering(inspect_ok:, running: "false")
+      h = helper
+      allow(h).to receive(:docker_command) do |cmd, _opts = {}|
+        raise Kitchen::ShellOut::ShellCommandFailed, "No such container" unless inspect_ok
+
+        cmd.include?("{{.State.Running}}") ? "#{running}\n" : "[{...}]"
+      end
+      h
+    end
+
+    let(:state) { { container_id: "abc123abc123" } }
+
+    it "reports a running container as existing and running" do
+      h = helper_answering(inspect_ok: true, running: "true")
+      expect(h.container_exists?(state)).to be true
+      expect(h.container_running?(state)).to be true
+    end
+
+    it "reports a stopped container as existing but not running" do
+      h = helper_answering(inspect_ok: true, running: "false")
+      expect(h.container_exists?(state)).to be true
+      expect(h.container_running?(state)).to be false
+    end
+
+    it "reports a container docker does not know as neither" do
+      h = helper_answering(inspect_ok: false)
+      expect(h.container_exists?(state)).to be false
+      expect(h.container_running?(state)).to be false
+    end
+
+    it "reports no container when state names none" do
+      h = helper
+      expect(h).not_to receive(:docker_command)
+      expect(h.container_exists?({})).to be false
+      expect(h.container_running?({})).to be false
+    end
+
+    it "asks docker about a container, not about its processes" do
+      # `docker top` was the original implementation and is the bug: it fails
+      # on a stopped container, which read as the container not existing.
+      h = helper
+      seen = []
+      allow(h).to receive(:docker_command) { |cmd, _opts = {}| seen << cmd; "[{...}]" }
+      h.container_exists?(state)
+      expect(seen.join).to include("inspect --type=container")
+      expect(seen.join).not_to include("top ")
+    end
+  end
+
   describe "#remove_container" do
     it "stops the container before removing it" do
       # `docker rm` refuses to remove a running container, so the order matters.

data/spec/container_spec.rb

@@ -0,0 +1,115 @@
+#
+# 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"
+
+describe Kitchen::Docker::Container do
+  subject(:container) { described_class.new(config) }
+
+  let(:config) { { username: "kitchen", remove_images: false } }
+  let(:state) { { container_id: "abc123abc123" } }
+
+  # A container that exists but has stopped is the case these two guard. It
+  # happens whenever the host reboots, the container's PID 1 exits, or someone
+  # runs `docker stop` -- so it is not an exotic state to be in.
+  def stub_container(exists:, running:)
+    allow(container).to receive(:container_exists?).and_return(exists)
+    allow(container).to receive(:container_running?).and_return(running)
+  end
+
+  describe "#destroy" do
+    it "removes a running container" do
+      stub_container(exists: true, running: true)
+      expect(container).to receive(:remove_container).with(state)
+      container.destroy(state)
+    end
+
+    it "removes a container that exists but has stopped" do
+      # Test Kitchen deletes the state file once destroy returns, so a stopped
+      # container skipped here is orphaned for good: nothing records its id any
+      # more, and `kitchen list` reports the instance as not created.
+      stub_container(exists: true, running: false)
+      expect(container).to receive(:remove_container).with(state)
+      container.destroy(state)
+    end
+
+    it "removes nothing when the container is already gone" do
+      stub_container(exists: false, running: false)
+      expect(container).not_to receive(:remove_container)
+      container.destroy(state)
+    end
+
+    context "with remove_images set" do
+      let(:config) { { username: "kitchen", remove_images: true } }
+      let(:state) { { container_id: "abc123abc123", image_id: "sha256:abc" } }
+
+      it "removes the image after the container" do
+        stub_container(exists: true, running: true)
+        allow(container).to receive(:image_exists?).and_return(true)
+        order = []
+        allow(container).to receive(:remove_container) { order << :container }
+        allow(container).to receive(:remove_image) { order << :image }
+
+        container.destroy(state)
+
+        expect(order).to eq %i{container image}
+      end
+    end
+  end
+
+  describe "#create" do
+    it "accepts a running container it has seen before" do
+      stub_container(exists: true, running: true)
+      expect { container.create(state) }.not_to raise_error
+    end
+
+    it "records the login user" do
+      stub_container(exists: true, running: true)
+      new_state = state.dup
+      container.create(new_state)
+      expect(new_state[:username]).to eq "kitchen"
+    end
+
+    it "refuses a container that exists but is not running, and says how to clear it" do
+      # Reporting this as "the container does not exist" left no way forward:
+      # the container is there, so the message has to point at destroy.
+      stub_container(exists: true, running: false)
+      expect { container.create(state) }
+        .to raise_error(Kitchen::ActionFailed, /is not running.*kitchen destroy/m)
+    end
+
+    it "refuses a container that state names but docker does not have" do
+      stub_container(exists: false, running: false)
+      expect { container.create(state) }
+        .to raise_error(Kitchen::ActionFailed, /does not exist/)
+    end
+
+    it "is happy to start from nothing" do
+      stub_container(exists: false, running: false)
+      expect { container.create({}) }.not_to raise_error
+    end
+
+    it "asks docker about the container only as often as it needs to" do
+      # The previous implementation called container_exists? twice on the path
+      # that raises, which is two `docker inspect` round trips for one answer.
+      stub_container(exists: false, running: false)
+      expect(container).to receive(:container_exists?).once.and_return(false)
+      begin
+        container.create(state)
+      rescue Kitchen::ActionFailed
+        nil
+      end
+    end
+  end
+end

data/spec/file_helper_spec.rb

@@ -0,0 +1,110 @@
+#
+# 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::Helpers::FileHelper do
+  around do |example|
+    Dir.mktmpdir { |dir| @dir = dir; example.run }
+  end
+
+  describe "#create_temp_file" do
+    it "writes the contents" do
+      path = File.join(@dir, "docker-abc.sh")
+      helper.create_temp_file(path, "echo hi\n")
+      expect(File.read(path)).to eq "echo hi\n"
+    end
+
+    it "creates the parent directory" do
+      # Container#execute writes to ./.kitchen/temp, which does not exist on a
+      # fresh checkout.
+      path = File.join(@dir, ".kitchen", "temp", "docker-abc.sh")
+      helper.create_temp_file(path, "echo hi\n")
+      expect(File.read(path)).to eq "echo hi\n"
+    end
+
+    it "replaces the contents of an existing file" do
+      path = File.join(@dir, "docker-abc.sh")
+      File.write(path, "old and longer content")
+      helper.create_temp_file(path, "new\n")
+      expect(File.read(path)).to eq "new\n"
+    end
+
+    it "leaves no open handle behind" do
+      path = File.join(@dir, "docker-abc.sh")
+      before = ObjectSpace.each_object(File).count { |f| !f.closed? }
+      helper.create_temp_file(path, "echo hi\n")
+      expect(ObjectSpace.each_object(File).count { |f| !f.closed? }).to eq before
+    end
+
+    # Every one of these used to raise "undefined method 'close' for an instance
+    # of String": the open failed, `file` was still the path, and the ensure
+    # tried to close it. The real cause never reached the user, who saw a Ruby
+    # NoMethodError reported as a Docker failure.
+    context "when the file cannot be written" do
+      it "reports a parent that is not a directory" do
+        # ".kitchen" existing as a file rather than a directory. The exact errno
+        # differs by platform -- macOS reports EEXIST from mkdir here, Linux
+        # ENOTDIR -- so the assertion is that the underlying cause reaches the
+        # user at all, which is what used to be lost.
+        blocker = File.join(@dir, "kitchen")
+        File.write(blocker, "not a directory")
+        path = File.join(blocker, "temp", "docker-abc.sh")
+
+        expect { helper.create_temp_file(path, "echo hi") }
+          .to raise_error(RuntimeError, /Failed to write temp file.*Error Details: \S+.*#{Regexp.escape(blocker)}/m)
+      end
+
+      it "reports a directory it may not write to" do
+        readonly = File.join(@dir, "readonly")
+        Dir.mkdir(readonly)
+        File.chmod(0o500, readonly)
+
+        begin
+          expect { helper.create_temp_file(File.join(readonly, "docker-abc.sh"), "echo hi") }
+            .to raise_error(RuntimeError, /Failed to write temp file.*Permission denied/m)
+        ensure
+          File.chmod(0o700, readonly)
+        end
+      end
+
+      it "reports a target that is itself a directory" do
+        target = File.join(@dir, "isadir")
+        Dir.mkdir(target)
+
+        expect { helper.create_temp_file(target, "echo hi") }
+          .to raise_error(RuntimeError, /Failed to write temp file/)
+      end
+
+      it "names the path it could not write" do
+        # The old message said only "Failed to write temp file", which did not
+        # say which one.
+        path = File.join(@dir, "isadir")
+        Dir.mkdir(path)
+
+        expect { helper.create_temp_file(path, "echo hi") }
+          .to raise_error(RuntimeError, /#{Regexp.escape(path)}/)
+      end
+
+      it "never raises NoMethodError" do
+        blocker = File.join(@dir, "kitchen")
+        File.write(blocker, "not a directory")
+
+        expect { helper.create_temp_file(File.join(blocker, "x.sh"), "echo hi") }
+          .not_to raise_error(NoMethodError)
+      end
+    end
+  end
+end

data/spec/image_helper_spec.rb

@@ -122,6 +122,45 @@ describe Kitchen::Docker::Helpers::ImageHelper do
     end
   end
 
+  describe "#image_in_use?" do
+    let(:image_id) { "sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc" }
+
+    def helper_seeing(output)
+      h = helper
+      @asked = nil
+      allow(h).to receive(:docker_command) { |cmd, _opts = {}| @asked = cmd; output }
+      h
+    end
+
+    it "reports the image as in use when a container references it" do
+      expect(helper_seeing("331a7cd151e4\n").image_in_use?(image_id: image_id)).to be true
+    end
+
+    it "reports the image as free when nothing references it" do
+      expect(helper_seeing("").image_in_use?(image_id: image_id)).to be false
+    end
+
+    it "reports the image as free when state names no image" do
+      h = helper
+      expect(h).not_to receive(:docker_command)
+      expect(h.image_in_use?({})).to be false
+    end
+
+    it "asks docker to filter, rather than searching ps output for the id" do
+      # `docker ps -a` abbreviates the IMAGE column to twelve characters, so
+      # searching it for the full sha256 digest never matched and the guard
+      # was always false.
+      h = helper_seeing("331a7cd151e4\n")
+      h.image_in_use?(image_id: image_id)
+      expect(@asked).to eq "ps -a -q --filter ancestor=#{image_id}"
+    end
+
+    it "does not mistake a warning on stderr for a container" do
+      expect(helper_seeing("WARNING: something happened\n").image_in_use?(image_id: image_id))
+        .to be false
+    end
+  end
+
   describe "#remove_image" do
     let(:state) { { image_id: "sha256:abc" } }
 

data/spec/linux_container_spec.rb

@@ -54,15 +54,28 @@ describe Kitchen::Docker::Container::Linux do
     # rescue clause cannot fire. Test Kitchen is then handed port 0 and fails
     # far away from here, complaining that SSH was refused.
     it "reads the published port from an IPv6-only daemon" do
-      pending "BUG: IPv6 output parses to port 0 rather than the published port"
       expect(port(DockerOutput::PORT_IPV6_ONLY)).to eq DockerOutput::PUBLISHED_PORT
     end
 
     it "refuses to report a port it could not parse" do
-      pending "BUG: unparseable output silently yields port 0 instead of raising"
       expect { port("") }.to raise_error(Kitchen::ActionFailed)
     end
 
+    it "reads the published port when docker names the host" do
+      expect(port("localhost:52239\n")).to eq DockerOutput::PUBLISHED_PORT
+    end
+
+    it "refuses to report a port from output with no port in it" do
+      expect { port("no public port '22/tcp' published\n") }
+        .to raise_error(Kitchen::ActionFailed, /Could not parse Docker port output/)
+    end
+
+    it "names the output it could not parse" do
+      # The previous message said only that parsing failed, which left nobody
+      # any way to tell what docker had actually printed.
+      expect { port("surprising\n") }.to raise_error(Kitchen::ActionFailed, /surprising/)
+    end
+
     it "never returns a port that cannot be connected to" do
       # The invariant behind both pending examples above: whatever this returns
       # has to be usable. Zero is not.
@@ -155,6 +168,51 @@ describe Kitchen::Docker::Container::Linux do
     end
   end
 
+  describe "#execute" do
+    # The command is staged as a script under .kitchen/temp and uploaded. That
+    # local copy has to go whether or not the rest of the run works, or a failing
+    # converge leaves a file behind on every attempt.
+    def container_in(dir, &upload)
+      c = container
+      allow(c).to receive(:create_dir_on_container)
+      allow(c).to receive(:replace_env_variables) { |_cfg, path| path }
+      allow(c).to receive(:container_exec).and_return("ok")
+      allow(c).to receive(:upload, &(upload || ->(*) { nil }))
+      allow(Dir).to receive(:pwd).and_return(dir)
+      c
+    end
+
+    around do |example|
+      Dir.chdir(@tmpdir) { example.run }
+    end
+
+    it "removes the staged script once the command has run" do
+      c = container_in(@tmpdir)
+      c.execute("echo hi")
+      expect(Dir.glob(".kitchen/temp/docker-*.sh")).to be_empty
+    end
+
+    it "removes the staged script when the upload fails" do
+      c = container_in(@tmpdir) { raise "upload exploded" }
+      expect { c.execute("echo hi") }.to raise_error(/Failed to execute command/)
+      expect(Dir.glob(".kitchen/temp/docker-*.sh")).to be_empty
+    end
+
+    it "removes the staged script when the command itself fails" do
+      c = container_in(@tmpdir)
+      allow(c).to receive(:container_exec).and_raise("command exploded")
+      expect { c.execute("echo hi") }.to raise_error(/Failed to execute command/)
+      expect(Dir.glob(".kitchen/temp/docker-*.sh")).to be_empty
+    end
+
+    it "uploads the command as the contents of the script" do
+      uploaded = nil
+      c = container_in(@tmpdir) { |local, _remote| uploaded = ::File.read(local) }
+      c.execute("echo hi")
+      expect(uploaded).to eq "echo hi"
+    end
+  end
+
   describe "#generate_keys" do
     it "writes a usable key pair when none exists" do
       private_key = File.join(@tmpdir, "generated")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-docker
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.3.3
 platform: ruby
 authors:
 - Sean Porter
@@ -74,9 +74,11 @@ files:
 - renovate.json
 - spec/cli_helper_spec.rb
 - spec/container_helper_spec.rb
+- spec/container_spec.rb
 - spec/docker_spec.rb
 - spec/dockerfile_helper_spec.rb
 - spec/erb_context_spec.rb
+- spec/file_helper_spec.rb
 - spec/image_helper_spec.rb
 - spec/inspec_helper_spec.rb
 - spec/linux_container_spec.rb