kitchen-docker 3.3.0 → 3.3.3

data/spec/container_helper_spec.rb

@@ -0,0 +1,292 @@
+#
+# 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::Helpers::ContainerHelper do
+  describe "#parse_container_id" do
+    it "accepts a full-length id" do
+      expect(helper.parse_container_id(DockerOutput::RUN_CLEAN))
+        .to eq DockerOutput::RUN_CONTAINER_ID
+    end
+
+    it "accepts a short id" do
+      expect(helper.parse_container_id("abc123abc123\n")).to eq "abc123abc123"
+    end
+
+    it "fails loudly when the output holds no id" do
+      expect { helper.parse_container_id("Error response from daemon: no such image\n") }
+        .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
+      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
+      expect(helper.parse_container_id(DockerOutput::RUN_WITH_SWAP_WARNING))
+        .to eq DockerOutput::RUN_CONTAINER_ID
+    end
+  end
+
+  describe "#remote_socket? and #socket_uri" do
+    {
+      "unix:///var/run/docker.sock" => false,
+      "npipe:////./pipe/docker_engine" => false,
+      "tcp://docker.example.com:2376" => true,
+      "tcp://127.0.0.1:2375" => true,
+    }.each do |socket, remote|
+      it "treats #{socket} as #{remote ? "remote" : "local"}" do
+        expect(helper(socket: socket).remote_socket?).to eq remote
+      end
+    end
+
+    it "reports a socket-less configuration as local" do
+      expect(helper(socket: nil).remote_socket?).to be false
+    end
+
+    it "exposes the socket as a URI" do
+      expect(helper(socket: "tcp://docker.example.com:2376").socket_uri.port).to eq 2376
+    end
+  end
+
+  describe "#dockerfile_proxy_config" do
+    it "is empty when no proxy is configured" do
+      expect(helper.dockerfile_proxy_config).to eq ""
+    end
+
+    # Tools inside the image disagree about the spelling, so both cases have to
+    # be set. Dropping either half breaks builds behind a proxy in a way that
+    # only shows up on somebody else's network.
+    {
+      http_proxy: %w{http_proxy HTTP_PROXY},
+      https_proxy: %w{https_proxy HTTPS_PROXY},
+      no_proxy: %w{no_proxy NO_PROXY},
+    }.each do |option, spellings|
+      it "sets #{spellings.join(" and ")} for #{option}" do
+        lines = helper(option => "http://proxy:8080").dockerfile_proxy_config.lines.map(&:strip)
+        spellings.each { |name| expect(lines).to include "ENV #{name}=http://proxy:8080" }
+      end
+    end
+
+    it "emits only the proxies that are configured" do
+      config = helper(http_proxy: "http://proxy:8080").dockerfile_proxy_config
+      expect(config).not_to match(/no_proxy|https_proxy/i)
+    end
+  end
+
+  describe "#container_env_variables" do
+    def with_printenv(output)
+      h = helper
+      allow(h).to receive(:docker_command).and_return(output)
+      h.container_env_variables(platform: "ubuntu-24.04")
+    end
+
+    it "reads the container's environment" do
+      expect(with_printenv("HOME=/root\nUSER=kitchen\n"))
+        .to eq("HOME" => "/root", "USER" => "kitchen")
+    end
+
+    # printenv output is `NAME=VALUE`, and values routinely contain `=`:
+    # LS_COLORS and any JAVA_OPTS-style variable do. Splitting on every `=`
+    # 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
+      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"}')
+      expect(h.container_env_variables(platform: "windows-2022"))
+        .to eq("TEMP" => 'C:\Users\ADMINI~1\AppData\Local\Temp')
+    end
+  end
+
+  describe "#replace_env_variables" do
+    let(:linux_state) { { platform: "ubuntu-24.04", container_id: "abc" } }
+    let(:windows_state) { { platform: "windows-2022", container_id: "abc" } }
+
+    def helper_returning(vars)
+      h = helper
+      allow(h).to receive(:container_env_variables).and_return(vars)
+      h
+    end
+
+    it "expands a POSIX $VAR reference" do
+      h = helper_returning("TEMP" => "/var/tmp")
+      expect(h.replace_env_variables(linux_state, "$TEMP/kitchen")).to eq "/var/tmp/kitchen"
+    end
+
+    it "expands a PowerShell $env:VAR reference" do
+      h = helper_returning("TEMP" => 'C:\Temp')
+      expect(h.replace_env_variables(windows_state, '$env:TEMP\kitchen')).to eq 'C:\Temp\kitchen'
+    end
+
+    it "leaves a path with no variable reference alone" do
+      expect(helper.replace_env_variables(linux_state, "/tmp/kitchen")).to eq "/tmp/kitchen"
+    end
+
+    it "substitutes an empty string when the variable is not set in the container" do
+      # Documents current behaviour rather than endorsing it: an unset variable
+      # silently yields a path like "/kitchen" instead of failing, and the
+      # upload then lands somewhere unexpected.
+      h = helper_returning({})
+      expect(h.replace_env_variables(linux_state, "$TEMP/kitchen")).to eq "/kitchen"
+    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.
+      h = helper
+      calls = []
+      allow(h).to receive(:docker_command) { |cmd| calls << cmd }
+      h.remove_container(container_id: "abc")
+      expect(calls).to eq ["stop -t 0 abc", "rm abc"]
+    end
+  end
+
+  describe "#copy_file_to_container" do
+    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")
+    end
+  end
+end

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/dockerfile_helper_spec.rb

@@ -13,97 +13,133 @@
 #
 
 require "spec_helper"
-require "kitchen/docker/helpers/dockerfile_helper"
 
 describe Kitchen::Docker::Helpers::DockerfileHelper do
-  let(:helper_class) do
-    Class.new do
-      include Kitchen::Docker::Helpers::DockerfileHelper
-      attr_accessor :config
+  # Every platform name the driver accepts, and the method it must route to.
+  # Adding a distribution means adding a `when` branch and a method, and it is
+  # easy to add one and forget the other -- the result being a platform that
+  # raises "Unknown platform" or, worse, quietly bootstraps with the wrong
+  # package manager.
+  PLATFORM_ROUTES = {
+    "arch" => :arch_platform,
+    "debian" => :debian_platform,
+    "ubuntu" => :debian_platform,
+    "fedora" => :fedora_platform,
+    "gentoo" => :gentoo_platform,
+    "gentoo-paludis" => :gentoo_paludis_platform,
+    "opensuse" => :opensuse_platform,
+    "opensuse/leap" => :opensuse_platform,
+    "opensuse/tumbleweed" => :opensuse_platform,
+    "sles" => :opensuse_platform,
+    "rhel" => :rhel_platform,
+    "centos" => :rhel_platform,
+    "oraclelinux" => :rhel_platform,
+    "amazonlinux" => :amazonlinux_platform,
+    "centosstream" => :centosstream_platform,
+    "almalinux" => :almalinux_platform,
+    "rockylinux" => :rockylinux_platform,
+    "photon" => :photonos_platform,
+  }.freeze
 
-      def initialize(config = {})
-        @config = config
+  describe "#dockerfile_platform" do
+    PLATFORM_ROUTES.each do |platform, method|
+      it "routes #{platform} to ##{method}" do
+        # Compared by output rather than by stubbing the method, so this also
+        # proves the branch is wired to a method that actually exists.
+        h = helper(platform: platform, disable_upstart: true)
+        expect(h.dockerfile_platform).to eq h.public_send(method)
       end
     end
+
+    it "names the platform it could not handle" do
+      # The error is what a user sees after a typo in kitchen.yml, so it has to
+      # contain the value they typed.
+      expect { helper(platform: "ubunut").dockerfile_platform }
+        .to raise_error(Kitchen::ActionFailed, /Unknown platform 'ubunut'/)
+    end
   end
 
-  let(:helper) { helper_class.new(platform:) }
+  # Test Kitchen reaches a Linux container over SSH as a sudo-capable user, so
+  # an image that lacks either an SSH server or sudo is useless no matter which
+  # distribution it is. These hold for every supported platform.
+  describe "invariants every platform's setup must satisfy" do
+    PLATFORM_ROUTES.values.uniq.each do |method|
+      context "##{method}" do
+        subject(:fragment) { helper(platform: "ubuntu", disable_upstart: true).public_send(method) }
+
+        it "installs sudo" do
+          expect(fragment).to match(/\bsudo\b/)
+        end
+
+        it "installs an SSH server" do
+          expect(fragment).to match(/openssh|\bssh\b/)
+        end
+
+        it "contains only Dockerfile instructions" do
+          # Catches a fragment that has picked up a stray shell line, which
+          # would fail the build with a parse error rather than anything that
+          # points back here.
+          instructions = fragment.lines.map(&:strip).reject(&:empty?)
+          continued = false
+          instructions.each do |line|
+            expect(line).to match(/\A(RUN|ENV|ARG|COPY|ADD|WORKDIR|USER)\b/) unless continued
+            continued = line.end_with?("\\")
+          end
+        end
+      end
+    end
+  end
 
   describe "#amazonlinux_platform" do
-    let(:platform) { "amazonlinux" }
+    subject(:fragment) { helper(platform: "amazonlinux").amazonlinux_platform }
 
-    it "includes --allowerasing flag for yum install" do
-      result = helper.amazonlinux_platform
-      expect(result).to include("yum install -y --allowerasing")
+    it "allows erasing conflicting packages, which Amazon Linux 2023 needs" do
+      expect(fragment).to include "--allowerasing"
     end
 
-    it "installs required packages including curl" do
-      result = helper.amazonlinux_platform
-      expect(result).to include("sudo openssh-server openssh-clients which curl")
+    it "installs curl" do
+      expect(fragment).to match(/curl/)
     end
 
-    it "sets container environment variable" do
-      result = helper.amazonlinux_platform
-      expect(result).to include("ENV container=docker")
+    it "marks the image as running in a container" do
+      expect(fragment).to include "ENV container=docker"
     end
 
-    it "generates SSH host key if missing" do
-      result = helper.amazonlinux_platform
-      expect(result).to include("ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key")
+    it "generates an SSH host key only if one is missing" do
+      # Regenerating on every build would change the host key under a user who
+      # already accepted it.
+      expect(fragment).to include '[ -f "/etc/ssh/ssh_host_rsa_key" ] ||'
     end
   end
 
   describe "#rhel_platform" do
-    let(:platform) { "rhel" }
+    subject(:fragment) { helper(platform: "rhel").rhel_platform }
 
-    it "does not include --allowerasing flag" do
-      result = helper.rhel_platform
-      expect(result).not_to include("--allowerasing")
+    it "does not pass --allowerasing, which older yum does not accept" do
+      expect(fragment).not_to include "--allowerasing"
     end
 
-    it "installs required packages including curl if needed" do
-      result = helper.rhel_platform
-      expect(result).to include("sudo openssh-server openssh-clients which")
-      expect(result).to include("which curl || yum install -y curl")
+    it "installs curl if it is not already present" do
+      expect(fragment).to match(/curl/)
     end
   end
 
-  describe "#dockerfile_platform" do
-    context "when platform is amazonlinux" do
-      let(:platform) { "amazonlinux" }
-
-      it "calls amazonlinux_platform method" do
-        expect(helper).to receive(:amazonlinux_platform).and_call_original
-        result = helper.dockerfile_platform
-        expect(result).to include("--allowerasing")
-      end
-    end
-
-    context "when platform is rhel" do
-      let(:platform) { "rhel" }
-
-      it "calls rhel_platform method" do
-        expect(helper).to receive(:rhel_platform).and_call_original
-        result = helper.dockerfile_platform
-        expect(result).not_to include("--allowerasing")
-      end
+  describe "#debian_platform" do
+    it "neutralises initctl when disable_upstart is set" do
+      expect(helper(platform: "ubuntu", disable_upstart: true).debian_platform)
+        .to include "dpkg-divert"
     end
 
-    context "when platform is centos" do
-      let(:platform) { "centos" }
-
-      it "calls rhel_platform method" do
-        expect(helper).to receive(:rhel_platform).and_call_original
-        helper.dockerfile_platform
-      end
+    it "leaves initctl alone when disable_upstart is false" do
+      expect(helper(platform: "ubuntu", disable_upstart: false).debian_platform)
+        .not_to include "dpkg-divert"
     end
 
-    context "when platform is oraclelinux" do
-      let(:platform) { "oraclelinux" }
-
-      it "calls rhel_platform method" do
-        expect(helper).to receive(:rhel_platform).and_call_original
-        helper.dockerfile_platform
+    it "keeps apt non-interactive either way" do
+      # A prompt during the build hangs it until Docker times out.
+      [true, false].each do |setting|
+        expect(helper(platform: "ubuntu", disable_upstart: setting).debian_platform)
+          .to include "ENV DEBIAN_FRONTEND=noninteractive"
       end
     end
   end

data/spec/erb_context_spec.rb

@@ -0,0 +1,60 @@
+#
+# 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::ERBContext do
+  def render(template, config)
+    ERB.new(template).result(described_class.new(config).get_binding)
+  end
+
+  # A user-supplied `dockerfile:` is rendered through ERB with the driver
+  # configuration exposed as instance variables. That is a documented part of
+  # the driver's interface -- test/Dockerfile depends on it -- so the exposure
+  # rules are worth pinning.
+  it "exposes each configuration key as an instance variable" do
+    expect(render("<%= @image %>", image: "ubuntu:24.04")).to eq "ubuntu:24.04"
+  end
+
+  it "exposes keys the driver has no option for" do
+    # kitchen.yml's dockerfile platform passes `password`, which the driver
+    # itself never reads; the template is the only consumer.
+    expect(render("<%= @password %>", password: "secret")).to eq "secret"
+  end
+
+  it "renders a missing key as empty rather than failing the build" do
+    expect(render("[<%= @nope %>]", {})).to eq "[]"
+  end
+
+  it "accepts string keys as well as symbols" do
+    expect(render("<%= @image %>", "image" => "alpine")).to eq "alpine"
+  end
+
+  it "allows a template to read a file, as test/Dockerfile does with the public key" do
+    Dir.mktmpdir do |dir|
+      key = File.join(dir, "k.pub")
+      File.write(key, "ssh-rsa AAAA test\n")
+      expect(render("<%= IO.read(@public_key).strip %>", public_key: key))
+        .to eq "ssh-rsa AAAA test"
+    end
+  end
+
+  it "keeps values verbatim, without escaping" do
+    # The template author decides on quoting; silently escaping here would
+    # corrupt Dockerfiles that already quote correctly.
+    expect(render("<%= @run_command %>", run_command: 'sshd -o "UseDNS=no"'))
+      .to eq 'sshd -o "UseDNS=no"'
+  end
+end